orca r4002 - trunk/docs/doc-set
- From: wwalker svn gnome org
- To: svn-commits-list gnome org
- Subject: orca r4002 - trunk/docs/doc-set
- Date: Wed, 25 Jun 2008 15:49:19 +0000 (UTC)
Author: wwalker
Date: Wed Jun 25 15:49:19 2008
New Revision: 4002
URL: http://svn.gnome.org/viewvc/orca?rev=4002&view=rev
Log:
Move spec and such to WIKI. Put user guide and internals in separate
docs.
Added:
trunk/docs/doc-set/internals.html
trunk/docs/doc-set/internals.pdf (contents, props changed)
trunk/docs/doc-set/user_guide.html
trunk/docs/doc-set/user_guide.pdf (contents, props changed)
Removed:
trunk/docs/doc-set/orca.html
trunk/docs/doc-set/orca.pdf
Added: trunk/docs/doc-set/internals.html
==============================================================================
--- (empty file)
+++ trunk/docs/doc-set/internals.html Wed Jun 25 15:49:19 2008
@@ -0,0 +1,3274 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd";>
+<HTML
+><HEAD
+><TITLE
+>Orca Technical Reference</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
+><BODY
+CLASS="BOOK"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="BOOK"
+><A
+NAME="AEN1"
+></A
+><DIV
+CLASS="TITLEPAGE"
+><H1
+CLASS="TITLE"
+><A
+NAME="AEN1"
+>Orca Technical Reference</A
+></H1
+><DIV
+CLASS="LEGALNOTICE"
+><P
+></P
+><A
+NAME="AEN4"
+></A
+><P
+>Copyright 2005-2008, Sun Microsystems, Inc.</P
+><P
+></P
+></DIV
+><HR></DIV
+><DIV
+CLASS="TOC"
+><DL
+><DT
+><B
+>Table of Contents</B
+></DT
+><DT
+><A
+HREF="#ARCHFORWARD"
+>Foreword</A
+></DT
+><DT
+>1. <A
+HREF="#PREREQ"
+>Prerequisites</A
+></DT
+><DD
+><DL
+><DT
+>1.1. <A
+HREF="#PREREQGNOME"
+>GNOME 2.22 or better</A
+></DT
+><DT
+>1.2. <A
+HREF="#PREREQPYTHON"
+>Python v2.4 or better</A
+></DT
+><DT
+>1.3. <A
+HREF="#PREREQBRLTTY"
+>BrlTTY v3.7.2 or better</A
+></DT
+><DT
+>1.4. <A
+HREF="#PREREQKEYBOARDNAV"
+>Keyboard Navigation</A
+></DT
+></DL
+></DD
+><DT
+>2. <A
+HREF="#ARCHITECTURE"
+>Architecture</A
+></DT
+><DD
+><DL
+><DT
+>2.1. <A
+HREF="#ARCHDESKTOP"
+>Desktop and AT-SPI</A
+></DT
+><DT
+>2.2. <A
+HREF="#ARCHORCA"
+>Orca Module</A
+></DT
+><DD
+><DL
+><DT
+>2.2.1. <A
+HREF="#ARCHSETTINGS"
+>settings</A
+></DT
+></DL
+></DD
+><DT
+>2.3. <A
+HREF="#SCRIPT"
+>Orca Scripts</A
+></DT
+><DT
+>2.4. <A
+HREF="#ARCHSYSTEMSERVICES"
+>System Services</A
+></DT
+><DD
+><DL
+><DT
+>2.4.1. <A
+HREF="#ARCHSPEECH"
+>speech</A
+></DT
+><DT
+>2.4.2. <A
+HREF="#ARCHBRAILLE"
+>braille</A
+></DT
+><DT
+>2.4.3. <A
+HREF="#ARCHMAG"
+>mag</A
+></DT
+></DL
+></DD
+></DL
+></DD
+><DT
+>3. <A
+HREF="#SCRIPTGUIDE"
+>Introduction to Scripting</A
+></DT
+><DD
+><DL
+><DT
+>3.1. <A
+HREF="#SGCONTRACT"
+>Script Contract</A
+></DT
+><DT
+>3.2. <A
+HREF="#SGLIFECYCLE"
+>Script Life Cycle</A
+></DT
+></DL
+></DD
+><DT
+>4. <A
+HREF="#CUSTOMIZATION"
+>Customized Behavior</A
+></DT
+><DD
+><DL
+><DT
+>4.1. <A
+HREF="#SGEVENTLISTENERS"
+>Defining Event Listeners</A
+></DT
+><DT
+>4.2. <A
+HREF="#SGINPUTEVENTHANDLERS"
+>Input Event Handlers</A
+></DT
+><DT
+>4.3. <A
+HREF="#SGKEYBINDINGS"
+>Defining Keyboard Bindings</A
+></DT
+><DT
+>4.4. <A
+HREF="#SGBRAILLEBINDINGS"
+>Defining Braille Bindings</A
+></DT
+></DL
+></DD
+><DT
+>5. <A
+HREF="#SGUTILITIES"
+>Script Utilities</A
+></DT
+><DD
+><DL
+><DT
+>5.1. <A
+HREF="#DEBUG"
+>Debug Utilities</A
+></DT
+><DT
+>5.2. <A
+HREF="#SGTTS"
+>Speech Synthesis</A
+></DT
+><DD
+><DL
+><DT
+>5.2.1. <A
+HREF="#SGSPEECHPY"
+><TT
+CLASS="LITERAL"
+>speech.py</TT
+></A
+></DT
+><DT
+>5.2.2. <A
+HREF="#SGSGPY"
+><TT
+CLASS="LITERAL"
+>speechgenerator.py</TT
+></A
+></DT
+></DL
+></DD
+><DT
+>5.3. <A
+HREF="#SGBRAILLEOUTPUT"
+>Braille Output</A
+></DT
+><DD
+><DL
+><DT
+>5.3.1. <A
+HREF="#SGBRAILLEPY"
+><TT
+CLASS="LITERAL"
+>braille.py</TT
+></A
+></DT
+><DT
+>5.3.2. <A
+HREF="#SGBGPY"
+><TT
+CLASS="LITERAL"
+>braillegenerator.py</TT
+></A
+></DT
+></DL
+></DD
+></DL
+></DD
+><DT
+>6. <A
+HREF="#I18N"
+>Internationalization (I18N) Support</A
+></DT
+><DT
+><A
+HREF="#ARCHBIBLIOGRAPHY"
+>Bibliography</A
+></DT
+></DL
+></DIV
+><DIV
+CLASS="LOT"
+><DL
+CLASS="LOT"
+><DT
+><B
+>List of Figures</B
+></DT
+><DT
+>2-1. <A
+HREF="#AEN36"
+>High Level Orca Architecture. The main components of Orca
+ are as follows: desktop applications that support the AT-SPI,
+ the AT-SPI registry and infrastructure, Orca itself, Orca
+ Scripts, and system services. The key communication between
+ the components is depicted.</A
+></DT
+><DT
+>4-1. <A
+HREF="#AEN335"
+>Orca Script Diagram</A
+></DT
+></DL
+></DIV
+><DIV
+CLASS="PREFACE"
+><HR><H1
+><A
+NAME="ARCHFORWARD"
+></A
+>Foreword</H1
+><P
+>Orca is a flexible, extensible, and powerful assistive
+ technology that provides end-user access to applications and
+ toolkits that support the AT-SPI (e.g., the GNOME desktop). With
+ early input from and continued engagement with its end users, Orca
+ has been designed and implemented by the Sun Microsystems, Inc.,
+ Accessibility Program Office.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> Orca is currently a work in progress. As a result, this
+ and other books in the Orca Documentation Series are under
+ continuous modification and are also in various states of
+ completeness.</P
+><P
+>This book covers the overall architecture of Orca, including
+ a portion on writing custom scripts. The bulk of the user
+ information and user experience design can be found on the Orca
+ WIKI at http://live.gnome.org/Orca.</P
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="PREREQ"
+></A
+>Chapter 1. Prerequisites</H1
+><P
+>To help narrow the scope of the Orca development activity,
+ Orca uses existing software where available. For example, as
+ mentioned in the requirements, Orca is a screen reader that
+ needs to be able to interact with speech synthesis, braille,
+ and screen magnification services, but it need not be the
+ provider of such services. Given this, Orca has the following
+ dependencies:</P
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="PREREQGNOME"
+>1.1. GNOME 2.22 or better</A
+></H2
+><P
+>The GNOME 2.22 desktop contains a number of bug fixes and
+ enhancements to the accessibility infrastructure. These are
+ needed for Orca to run properly. GNOME 2.22 also packages a
+ variety of other dependencies of Orca, including gnome-speech,
+ gnome-mag, pyatspi, etc.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="PREREQPYTHON"
+>1.2. Python v2.4 or better</A
+></H2
+><P
+>Orca is written in the Python programming language and
+ depends upon features found in Python versions 2.4 and
+ greater.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="PREREQBRLTTY"
+>1.3. BrlTTY v3.7.2 or better</A
+></H2
+><P
+>BrlTTY [<SPAN
+CLASS="CITATION"
+><A
+HREF="#BRLTTY"
+><I
+>BRLTTY</I
+></A
+>></SPAN
+>] provides access to a
+ variety of Braille displays, and consists of a library and a
+ daemon to provide programmatic interaction with the
+ display.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="PREREQKEYBOARDNAV"
+>1.4. Keyboard Navigation</A
+></H2
+><P
+>As much as possible, Orca relies upon the keyboard
+ navigation methods built in to the native platform. For
+ example, it is expected that the native platform will provide
+ access via traditional methods such as the "tab" key, keyboard
+ mnemonics, and keyboard accelerators.</P
+></DIV
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="ARCHITECTURE"
+></A
+>Chapter 2. Architecture</H1
+><P
+>The Orca architecture has been driven primarily by the Orca
+ User Experience Design. There are two primary operating modes
+ of Orca: a focus tracking mode and a flat review mode.</P
+><P
+>The focus tracking mode generally relies upon applications
+ to provide reasonable keyboard navigation techniques to allow
+ the user to operate the application without requiring the mouse.
+ As the user uses traditional keyboard navigation techniques to
+ move from component to component in the application (e.g.,
+ pressing the Tab key to move from pushbutton to text area to
+ toggle button, etc.), Orca will present this to the user via
+ braille, speech, magnification, or a combination thereof. In
+ the cases where more complex navigation is needed, such as
+ structural navigation of complex text documents, Orca also
+ provides a facility to define keyboard and braille input events
+ that it can intercept and handle appropriately.</P
+><P
+>The flat review mode provides the user with the ability to
+ spatially navigate a window, giving them the ability to explore
+ as well as discover and interact with components in the window.
+ Orca provides a default set of keybindings for flat review, and
+ these keybindings can be easily redefined by the user.</P
+><P
+>The various modes of Orca are handled by "scripts," which
+ are Python modules that can provide a custom interpretation of
+ an application's interaction model. It is not intended that
+ there will be a unique script for every application. Instead,
+ it is expected that there will be a general purpose script that
+ covers a large number of applications. In the event that more
+ compelling or custom behavior is desired for an application,
+ however, one can use a custom script for the application.
+ Furthermore, scripts can subclass other scripts, allowing
+ them to be quite simple.</P
+><P
+>As illustrated in the high level Orca architecture diagram,
+ the main components of Orca are as follows: desktop applications
+ that support the AT-SPI, the AT-SPI registry and infrastructure,
+ Orca itself, Orca Scripts, and system services (e.g., speech,
+ braille, magnification).</P
+><DIV
+CLASS="FIGURE"
+><A
+NAME="AEN36"
+></A
+><P
+><B
+>Figure 2-1. High Level Orca Architecture. The main components of Orca
+ are as follows: desktop applications that support the AT-SPI,
+ the AT-SPI registry and infrastructure, Orca itself, Orca
+ Scripts, and system services. The key communication between
+ the components is depicted.</B
+></P
+><DIV
+CLASS="MEDIAOBJECT"
+><P
+><IMG
+SRC="architecture.jpg"></P
+></DIV
+></DIV
+><P
+>The following sections describe the architecture in more
+ detail.</P
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="ARCHDESKTOP"
+>2.1. Desktop and AT-SPI</A
+></H2
+><P
+>Orca's sole view of any application on the desktop is via
+ the AT-SPI [<SPAN
+CLASS="CITATION"
+><A
+HREF="#AT-SPI"
+><I
+>AT-SPI</I
+></A
+>></SPAN
+>]. The AT-SPI is an
+ IDL/CORBA/Bonobo-based technology [<SPAN
+CLASS="CITATION"
+><A
+HREF="#BONOBO"
+><I
+>Bonobo</I
+></A
+>></SPAN
+>] that provides a common
+ interface for the desktop and its applications to expose their
+ GUI component hierarchy to assistive technologies such as
+ Orca. AT-SPI support is provided by toolkits such as GNOME's
+ GTK+ toolkit (via gail [<SPAN
+CLASS="CITATION"
+><A
+HREF="#GAIL"
+><I
+>GAIL</I
+></A
+>></SPAN
+>]), the Java platform (via
+ the Java access bridge), and the custom
+ toolkits used by applications such as Mozilla and Open
+ Office. Future support includes the Qt toolkit of KDE.</P
+><P
+>Assistive Technologies interact with the AT-SPI via two
+ primary means: the AT-SPI registry and accessible objects.
+ The AT-SPI registry permits assistive technologies to discover
+ existing applications on the desktop and to register for event
+ notification for AT-SPI events (e.g., window creation, focus
+ changes, object state changes, etc.) and device events (e.g.,
+ keyboard input events). Accessible objects provide the
+ assistive technology with information about the application,
+ and tend to mirror the actual GUI component hierarchy.
+ Accessible objects can be obtained in three ways: </P
+><P
+></P
+><OL
+TYPE="1"
+><LI
+><P
+>From the AT-SPI registry via queries on the desktop</P
+></LI
+><LI
+><P
+>From an AT-SPI event</P
+></LI
+><LI
+><P
+>From another Accessible via parent/child relationships
+ and other relationships such as "label for" and
+ "labeled by".</P
+></LI
+></OL
+><P
+>Orca's interaction with the AT-SPI is managed through
+ Orca's <TT
+CLASS="LITERAL"
+>atspi.py</TT
+> module. The
+ <TT
+CLASS="LITERAL"
+>atspi.py</TT
+> module communicates directly with
+ the AT-SPI via the AT-SPI IDL interfaces and also provides a
+ number of classes that help with AT-SPI interaction:
+ <TT
+CLASS="LITERAL"
+>Registry</TT
+>, <TT
+CLASS="LITERAL"
+>Accessible</TT
+>,
+ and <TT
+CLASS="LITERAL"
+>Event</TT
+>. The full documentation for
+ each of these classes is available in the pydoc for Orca
+ while the following paragraphs provide a brief overview.</P
+><P
+>The <TT
+CLASS="LITERAL"
+>Registry</TT
+> class provides a singleton
+ class instance to access to the AT-SPI
+ registry. It provides convenience methods for registering
+ AT-SPI event listeners and device event listeners, and also
+ provides the mechanism for starting and stopping event
+ delivery from the AT-SPI registry.</P
+><P
+>The <TT
+CLASS="LITERAL"
+>Accessible</TT
+> class provides a wrapper
+ for communicating with CORBA objects that implement the AT-SPI
+ Accessible and Application interfaces. Using Python's ability
+ to add new properties to a class instance at run time, Orca
+ can also annotate Accessible class instances with additional
+ information. The main purpose of an Accessible is to provide
+ a local cache for accessible objects, preventing the need for
+ numerous round trip calls to the AT-SPI registry and
+ application for information.</P
+><P
+>The <TT
+CLASS="LITERAL"
+>Event</TT
+> class provides a wrapper for
+ converting AT-SPI events into Python <TT
+CLASS="LITERAL"
+>Event</TT
+>
+ instances. The main purpose is to convert the AT-SPI
+ accessible source of the event into a Python
+ <TT
+CLASS="LITERAL"
+>Accessible</TT
+> instance and to also provide an
+ <TT
+CLASS="LITERAL"
+>Event</TT
+> instance that can be annotated by
+ scripts (the actual AT-SPI event delivered by the registry is
+ read-only).</P
+><P
+>As illustrated in the high level Orca architecture
+ diagram, the <TT
+CLASS="LITERAL"
+>atspi</TT
+> module has been used to
+ register event and device listeners with the AT-SPI registry.
+ Each exemplary desktop application (Firefox, NetBeans, GAIM,
+ StarOffice) emits AT-SPI events to the AT-SPI registry which
+ then delivers them to the <TT
+CLASS="LITERAL"
+>atspi</TT
+> module.
+ The <TT
+CLASS="LITERAL"
+>atspi</TT
+> module then calls all appropriate
+ listeners for the events it receives from the AT-SPI
+ registry.</P
+><P
+>In this case, the <TT
+CLASS="LITERAL"
+>orca</TT
+> module receives
+ keyboard events, which it interprets and also sends on to the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> module. Of more
+ interest, however, is that the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> module receives
+ AT-SPI events which it then passes on the script for the
+ application associated with the event. If there is no script,
+ the <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> will create an
+ instance of the default script. See the <A
+HREF="#SCRIPTGUIDE"
+>Orca Script Writing Guide</A
+> for
+ more information.</P
+><P
+>The <TT
+CLASS="LITERAL"
+>atspi</TT
+> module also registers its
+ own set of event listeners that it uses to keep its local
+ cache of accessible objects up to date.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> Because processing AT-SPI object events can be
+ time consuming, and because the notification of AT-SPI object
+ events is relatively "bursty," the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> maintains a queue
+ of AT-SPI object and input device events. It adds the events
+ to this queue when it receives them and processes the events
+ on the GLib idle handling thread. This permits Orca to
+ survive a relatively long burst of events and also allows it
+ to handle the events on a thread that is compatible with
+ GLib.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="ARCHORCA"
+>2.2. Orca Module</A
+></H2
+><P
+>The <TT
+CLASS="LITERAL"
+>orca</TT
+> module is the "main entry
+ point" of Orca. It initializes the components that Orca uses
+ (atspi, speech, braille, mag) and loads the user's settings.
+ It also is the first to receive all keyboard and braille input
+ events and delves them out to other Orca components
+ appropriately.</P
+><P
+>The <TT
+CLASS="LITERAL"
+>orca</TT
+> module maintains the current
+ known "locus of focus" in the <TT
+CLASS="LITERAL"
+>locusOfFocus</TT
+>
+ field of the <TT
+CLASS="LITERAL"
+>orca_state</TT
+> module. The
+ <TT
+CLASS="LITERAL"
+>locusOfFocus</TT
+> is intended to represent the
+ current object that the user is working with. In simple
+ terms, it is the object that is highlighted or has the dotted
+ line drawn around it. Be advised that the notion of "focus"
+ differs from toolkit to toolkit. For example, the object with
+ toolkit focus may actually be the parent of the object that is
+ highlighted. The <TT
+CLASS="LITERAL"
+>locusOfFocus</TT
+> is an an
+ attempt to neutralize these differences across toolkits: the
+ locus of focus is the individual object that is highlighted,
+ has the caret, etc.</P
+><P
+>Orca scripts set the locus of focus to inform Orca when
+ the locus of focus has changed. In addition, in the event
+ that there was a visual appearance change to the object that
+ has the locus of focus, the <TT
+CLASS="LITERAL"
+>orca</TT
+> module
+ provides a <TT
+CLASS="LITERAL"
+>visualAppearanceChanged</TT
+> that
+ scripts can use to inform Orca of this event.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> The <TT
+CLASS="LITERAL"
+>orca_state.locusOfFocus</TT
+>
+ field is intended to be set only via the
+ <TT
+CLASS="LITERAL"
+>setLocusOfFocus</TT
+> method of the
+ <TT
+CLASS="LITERAL"
+>orca</TT
+> module. Because the
+ <TT
+CLASS="LITERAL"
+>setLocusOfFocus</TT
+> method performs bookkeeping
+ and other tasks, the
+ <TT
+CLASS="LITERAL"
+>orca_state.locusOfFocus</TT
+> field should never
+ be set directly.</P
+><DIV
+CLASS="SECTION"
+><HR><H3
+CLASS="SECTION"
+><A
+NAME="ARCHSETTINGS"
+>2.2.1. settings</A
+></H3
+><P
+>The <SPAN
+CLASS="bold"
+><B
+CLASS="EMPHASIS"
+>settings</B
+></SPAN
+> module
+ (not depicted in the high level Orca architecture diagram)
+ holds preferences set by the user during configuration.
+ These settings include the following: use of speech and/or
+ braille, voice styles, key echo, text echo, and command
+ echo.</P
+><P
+>Any Orca module can check the value of a setting by
+ examining the field directly in the
+ <TT
+CLASS="LITERAL"
+>settings</TT
+> module. In addition, the
+ <TT
+CLASS="LITERAL"
+>orca</TT
+> module will import the
+ <TT
+CLASS="LITERAL"
+>user-settings</TT
+> module from the
+ <TT
+CLASS="LITERAL"
+>~/.orca directory</TT
+>, if it exists (it
+ is created as part of the configuration process that
+ is run the first time Orca is used or when the user
+ presses Insert+Space to invoke the configuration GUI).</P
+><P
+>The <TT
+CLASS="LITERAL"
+>user-settings</TT
+> module is a Python
+ script, allowing it to contain functions, class definitions,
+ etc. The primary job of the
+ <TT
+CLASS="LITERAL"
+>user-settings</TT
+> is to directly set the
+ values of fields in the <TT
+CLASS="LITERAL"
+>settings</TT
+>
+ module.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> the <TT
+CLASS="LITERAL"
+>init</TT
+> method of the
+ <TT
+CLASS="LITERAL"
+>orca</TT
+> module obtains settings. As a
+ result, the <TT
+CLASS="LITERAL"
+>user-settings</TT
+> module is
+ imported very early in the Orca life cycle.</P
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SCRIPT"
+>2.3. Orca Scripts</A
+></H2
+><P
+>Internally, the <TT
+CLASS="LITERAL"
+>orca</TT
+> module keeps track
+ of list of <TT
+CLASS="LITERAL"
+>PresentationManager</TT
+> instances
+ (see the pydoc for
+ <TT
+CLASS="LITERAL"
+>presentation_manager.py</TT
+>). The
+ <TT
+CLASS="LITERAL"
+>FocusTrackingPresenter</TT
+> (see
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>) is of the most
+ interest, as it is the <TT
+CLASS="LITERAL"
+>PresentationManager</TT
+>
+ that manages scripts.</P
+><P
+>Details on the <TT
+CLASS="LITERAL"
+>FocusTrackingPresenter</TT
+>
+ and Orca scripts can be found in the
+ <A
+HREF="#SCRIPTGUIDE"
+>Orca Script Writing Guide</A
+>.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="ARCHSYSTEMSERVICES"
+>2.4. System Services</A
+></H2
+><P
+> Orca relies on existing system services to provide
+ support for speech synthesis, braille, and screen
+ magnification. To interact with these services, Orca provides
+ the modules described in the following sections.
+ </P
+><DIV
+CLASS="SECTION"
+><HR><H3
+CLASS="SECTION"
+><A
+NAME="ARCHSPEECH"
+>2.4.1. speech</A
+></H3
+><P
+>The <SPAN
+CLASS="bold"
+><B
+CLASS="EMPHASIS"
+>speech</B
+></SPAN
+> module
+ provides Orca's Python interface to system speech services.
+ Each speech service is generated by a "speech server
+ factory." There are currently two such factories: one for
+ [<SPAN
+CLASS="CITATION"
+><A
+HREF="#GNOME-SPEECH"
+><I
+>gnome-speech</I
+></A
+>></SPAN
+>] (see
+ <TT
+CLASS="LITERAL"
+>gnomespeechfactory.py</TT
+> and one for
+ [<SPAN
+CLASS="CITATION"
+><A
+HREF="#EMACSPEAK"
+><I
+>Emacspeak</I
+></A
+>></SPAN
+>] (see
+ <TT
+CLASS="LITERAL"
+>espeechfactory.py</TT
+>), though it is expected
+ that support for other factories can be added in the
+ future.</P
+><P
+>Each speech factory offers up a list of
+ <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+>s, where each
+ <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+> is typically an interface to
+ a particular speech engine. For example, the
+ <TT
+CLASS="LITERAL"
+>espeechfactory</TT
+> will offer up a
+ <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+> that talks to the Fonix
+ DECtalk engine and a <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+> that
+ talks to the IBMTTS engine. Likewise, the
+ <TT
+CLASS="LITERAL"
+>gnomespeechfactory</TT
+> will offer up a
+ <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+> that uses the
+ <TT
+CLASS="LITERAL"
+>gnome-speech</TT
+> interface to talk to the
+ Festival Speech Synthesis System, a separate
+ <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+> that also uses the
+ <TT
+CLASS="LITERAL"
+>gnome-speech</TT
+> interface to talk to the
+ Fonix DECtalk engine, and so on.</P
+><P
+>Each <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+> instance then provides
+ a set of methods for actually speaking. Each of the methods
+ accepts an <TT
+CLASS="LITERAL"
+>ACSS</TT
+> instance, which represents
+ an aural cascading style sheet ([<SPAN
+CLASS="CITATION"
+><A
+HREF="#ACSS"
+><I
+>ACSS</I
+></A
+>></SPAN
+>]) that defines the voice
+ and voice parameter settings to use.</P
+><P
+>As part of the <TT
+CLASS="LITERAL"
+>orca-setup</TT
+> process,
+ the user selects a particular speech factory,
+ <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+>, and voice to use as their
+ default voice. When Orca starts, the
+ <TT
+CLASS="LITERAL"
+>speech</TT
+> module looks for these settings
+ and connects to the appropriate speech factory and
+ <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+>. In the event the a
+ connection cannot be made, the <TT
+CLASS="LITERAL"
+>speech</TT
+>
+ module attempts to find a working synthesis engine to use by
+ examining its list of speech factories. The
+ <TT
+CLASS="LITERAL"
+>speech</TT
+> module then provides simple
+ methods that delegate to the <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+>
+ instance. This model allows scripts to use their own
+ <TT
+CLASS="LITERAL"
+>SpeechServer</TT
+> instances if they wish, but
+ scripts typically just rely upon the user's default
+ preferences.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H3
+CLASS="SECTION"
+><A
+NAME="ARCHBRAILLE"
+>2.4.2. braille</A
+></H3
+><P
+> The <SPAN
+CLASS="bold"
+><B
+CLASS="EMPHASIS"
+>braille</B
+></SPAN
+> module
+ provides Orca's Python interface to the system's BrlTTY
+ [<SPAN
+CLASS="CITATION"
+><A
+HREF="#BRLTTY"
+><I
+>BRLTTY</I
+></A
+>></SPAN
+>] daemon. The BrlTTY
+ daemon, in turn, provides the interface to braille devices
+ for both displaying braille and receiving input from the
+ user.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>TODO:</I
+></SPAN
+> flesh this section out more.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H3
+CLASS="SECTION"
+><A
+NAME="ARCHMAG"
+>2.4.3. mag</A
+></H3
+><P
+> The <SPAN
+CLASS="bold"
+><B
+CLASS="EMPHASIS"
+>mag</B
+></SPAN
+> module
+ provides Orca's Python interface to the system's gnome-mag
+ [<SPAN
+CLASS="CITATION"
+><A
+HREF="#GNOME-MAG"
+><I
+>gnome-mag</I
+></A
+>></SPAN
+>] CORBA service(s).
+ The magnification component provides methods that permit
+ Orca discover screen magnification services and set their
+ desktop region of interest.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>TODO:</I
+></SPAN
+> flesh this section out more.</P
+></DIV
+></DIV
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="SCRIPTGUIDE"
+></A
+>Chapter 3. Introduction to Scripting</H1
+><P
+>In this section, you will learn more about the Orca
+ architecture as well as how to create your own custom scripts
+ for Orca.</P
+><P
+>The goal of scripting is to provide Orca with the capability
+ of providing a natural feeling and compelling user experience
+ for the various user interaction models of different desktop
+ applications.</P
+><P
+>The Orca scripting approach allows scripts to extend and/or
+ override the behavior of other scripts, thus simplifying the job
+ of a script writer. To further facilitate script writing, Orca
+ provides a "default" script that provides a reasonable default
+ behavior for Orca. This will not only serve as the "fallback
+ script" for Orca, but will also typically serve as the "jumping
+ off" point for writing custom scripts. Furthermore, keep in
+ mind that the "default" script is intended to cover a large
+ variety of applications. As such, you may find that it is
+ not necessary to write a custom script.</P
+><P
+>The primary operating mode of Orca is "focus tracking
+ mode," where Orca keeps track of the most relevant user
+ interface object that has keyboard focus. When Orca detects
+ changes to this object, which Orca refers to as the "locus of
+ focus," Orca will present relevant information to the user.</P
+><P
+>As such, the primary goal of a script is to assist Orca in
+ tracking of the locus of focus as well as presenting information
+ about the locus of focus. A script does this by registering for
+ one or more AT-SPI events and then reacting appropriately when
+ it receives those events. A script can also intercept and
+ interpret keystrokes and braille input events, allowing it to
+ further extend the behavior of Orca.</P
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SGCONTRACT"
+>3.1. Script Contract</A
+></H2
+><P
+>The contract for a script is documented in detail in the
+ pydoc of the <TT
+CLASS="LITERAL"
+>Script</TT
+> class in the
+ <TT
+CLASS="LITERAL"
+>script.py</TT
+> module. The
+ <TT
+CLASS="LITERAL"
+>Script</TT
+> subclass defined in the
+ <TT
+CLASS="LITERAL"
+>default.py</TT
+> module provides the default
+ behavior for Orca when it encounters applications and toolkits
+ that behave like the GTK toolkit. It is expected that new
+ scripts will typically extend the <TT
+CLASS="LITERAL"
+>Script</TT
+>
+ subclass of the <TT
+CLASS="LITERAL"
+>default.py</TT
+> module rather
+ than directly extending the <TT
+CLASS="LITERAL"
+>Script</TT
+> class
+ defined in the <TT
+CLASS="LITERAL"
+>script.py</TT
+> module.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SGLIFECYCLE"
+>3.2. Script Life Cycle</A
+></H2
+><P
+>BIRTH: Orca's <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>
+ module is the sole maintainer of scripts. Whenever it receives
+ an event from the AT-SPI Registry, the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> will determine the
+ application associated with that event and create a new script
+ for that application if on has not yet been created. Only one
+ script instance per application instance is allowed by the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>.</P
+><P
+>The script creation process consists of the following
+ steps:</P
+><P
+></P
+><UL
+><LI
+><P
+>The <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> will
+ attempt to perform a Python <TT
+CLASS="LITERAL"
+>import</TT
+>
+ using the application name as the name of an Orca module.
+ For example, for the <TT
+CLASS="LITERAL"
+>gnome-terminal</TT
+>
+ application, the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> will look for
+ the <TT
+CLASS="LITERAL"
+>gnome-terminal.py</TT
+> in the
+ <TT
+CLASS="LITERAL"
+>orca.scripts</TT
+> package (see the script
+ naming discussion in the <A
+HREF="#DEBUG"
+>debug
+ utilities section</A
+> to determine what to name your
+ script). If it cannot find such a module in the Python
+ search path, the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> will then
+ check in the <TT
+CLASS="LITERAL"
+>orca</TT
+> package for a module
+ matching the name of the toolkit used by the application.
+ Failing that, Orca will create an instance of the
+ <TT
+CLASS="LITERAL"
+>Script</TT
+> class defined in the
+ <TT
+CLASS="LITERAL"
+>default.py</TT
+> module.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> the <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>
+ also maintains a table to map application names to script
+ names. This is useful in many cases, such as if the
+ application name changes over time or the application
+ contains characters that are awkward in file system names.
+ To extend or override this table, one can call the
+ <TT
+CLASS="LITERAL"
+>setScriptMapping</TT
+> method of the
+ <TT
+CLASS="LITERAL"
+>settings</TT
+> module.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> it is possible to tell Orca to bypass all
+ custom script creation by setting
+ <TT
+CLASS="LITERAL"
+>orca.settings.enableCustomScripts=False</TT
+>
+ in your <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+>
+ module. This can be useful for debugging purposes.</P
+></LI
+><LI
+><P
+>Each script module is expected to provide a
+ <TT
+CLASS="LITERAL"
+>Script</TT
+> class that ultimately extends
+ the <TT
+CLASS="LITERAL"
+>orca.Script</TT
+> class defined in the
+ <TT
+CLASS="LITERAL"
+>script.py</TT
+> module. The constructor
+ takes the accessible application object as an
+ argument.</P
+><P
+>The constructor for the <TT
+CLASS="LITERAL"
+>Script</TT
+>
+ instance is expected to define any keystrokes, braille
+ buttons, and AT-SPI event listeners it is interested in
+ (see the <A
+HREF="#CUSTOMIZATION"
+>Customized
+ Behavior</A
+> section for how to do this).</P
+></LI
+><LI
+><P
+>Once it has created a script, the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> will register
+ event listeners for all AT-SPI events associated with
+ script (i.e., the script should not register these events
+ itself). When the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> receives the
+ events, it will pass the event to the script associated
+ with the event, regardless if the application associated
+ with the script has focus or not.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> registers its
+ own <TT
+CLASS="LITERAL"
+>processObjectEvent</TT
+> method as the
+ AT-SPI event listener. This method finds (and creates if
+ necessary) the script associated with the event and passes
+ the event onto the required
+ <TT
+CLASS="LITERAL"
+>processObjectEvent</TT
+> method of the script
+ for processing. Each <TT
+CLASS="LITERAL"
+>Event</TT
+> (see the
+ <TT
+CLASS="LITERAL"
+>atspi</TT
+> module) has the following
+ fields:</P
+><P
+></P
+><UL
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>source</TT
+>: an
+ <TT
+CLASS="LITERAL"
+>Accessible</TT
+> (see the
+ <TT
+CLASS="LITERAL"
+>atspi</TT
+> module) instance representing
+ the object associated with the event</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>type</TT
+>: a string describing the
+ event (e.g.,
+ <TT
+CLASS="LITERAL"
+>window:activated</TT
+>)</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>detail1</TT
+> and
+ <TT
+CLASS="LITERAL"
+>detail2</TT
+>: integer details for the
+ event (see the AT-SPI documentation)</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>any_data</TT
+>: something associated
+ with the event (see the AT-SPI documentation)</P
+></LI
+></UL
+></LI
+><LI
+><P
+>The <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> also
+ keeps track of the active script (as determined by the
+ script associated with the currently active window) and
+ will pass all keyboard and braille input events to the
+ active script.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> implements the
+ <TT
+CLASS="LITERAL"
+>processKeyboardEvent</TT
+> and
+ <TT
+CLASS="LITERAL"
+>processBrailleEvent</TT
+> methods which are
+ called by the main <TT
+CLASS="LITERAL"
+>orca</TT
+> module whenever
+ it receives a keystroke or braille input event. The
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> will pass
+ these events onto the
+ <TT
+CLASS="LITERAL"
+>processKeyboardEvent</TT
+> and
+ <TT
+CLASS="LITERAL"
+>processBrailleEvent</TT
+> methods of the
+ active script.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> Because processing AT-SPI object events can
+ be time consuming, and because the notification of AT-SPI
+ object events is relatively "bursty," the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> maintains a
+ queue of AT-SPI object and input device events. It adds
+ the events to this queue when it receives them and
+ processes the events on the GLib idle handling thread.
+ This permits Orca to survive a relatively long burst of
+ events and also allows it to handle the events on a thread
+ that is compatible with GLib.</P
+></LI
+></UL
+><P
+>LIFE: Whenever a script receives an event, the script can do
+ whatever it wants. Its primary task, however, is to assist
+ Orca in keeping track of the locus of focus. When a script
+ detects a change in the locus of focus, it should call
+ <TT
+CLASS="LITERAL"
+>orca.setLocusOfFocus</TT
+> with the
+ <TT
+CLASS="LITERAL"
+>Accessible</TT
+> object instance that is the new
+ locus of focus. Among other things, this results in the
+ <TT
+CLASS="LITERAL"
+>orca_state.locusOfFocus</TT
+> field being updated.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> The <TT
+CLASS="LITERAL"
+>orca_state.locusOfFocus</TT
+>
+ field is intended to be set only via the
+ <TT
+CLASS="LITERAL"
+>setLocusOfFocus</TT
+> method of the
+ <TT
+CLASS="LITERAL"
+>orca</TT
+> module. Because the
+ <TT
+CLASS="LITERAL"
+>setLocusOfFocus</TT
+> method performs bookkeeping
+ and other tasks, the
+ <TT
+CLASS="LITERAL"
+>orca_state.locusOfFocus</TT
+> field should never
+ be set directly.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> The <TT
+CLASS="LITERAL"
+>orca</TT
+> module has logic to
+ detect if the locus of focus really changed and will propagate
+ the change on as appropriate. The
+ <TT
+CLASS="LITERAL"
+>orca.setLocusOfFocus</TT
+> method first sends the
+ change to the <TT
+CLASS="LITERAL"
+>locusOfFocusChanged</TT
+> method of
+ the <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>, which then
+ passes the change onto the required
+ <TT
+CLASS="LITERAL"
+>locusOfFocusChanged</TT
+> method of the active
+ script. The <TT
+CLASS="LITERAL"
+>locusOfFocusChanged</TT
+> method is
+ the primary place where a script will present information to
+ the user.</P
+><P
+>In many cases, the locus of focus doesn't change, but some
+ property of the current locus of focus changes. For example,
+ a checkbox is checked or unchecked, yet remains as the locus
+ of focus. In these cases, a script should also keep Orca
+ informed by calling
+ <TT
+CLASS="LITERAL"
+>orca.visualAppearanceChanged</TT
+>.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> Like the <TT
+CLASS="LITERAL"
+>locusOfFocusChanged</TT
+>
+ method, the <TT
+CLASS="LITERAL"
+>visualAppearanceChanged</TT
+> method
+ of the <TT
+CLASS="LITERAL"
+>orca</TT
+> module will first call the
+ <TT
+CLASS="LITERAL"
+>visualAppearanceChanged</TT
+> method of the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>, which will then
+ call the required <TT
+CLASS="LITERAL"
+>visualAppearanceChanged</TT
+>
+ of the active script. The
+ <TT
+CLASS="LITERAL"
+>visualAppearanceChanged</TT
+> is the primary
+ place where a script will present such information to the
+ user.</P
+><P
+>DEATH: Whenever the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> detects that an
+ application has gone away (by determining that the application
+ has been removed from the desktop), it will delete the script
+ for that application and unregister any event listeners
+ associated with that script.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>IMPLEMENTATION DETAIL:</I
+></SPAN
+> the <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>
+ determines an application has gone away by detecting a
+ <TT
+CLASS="LITERAL"
+>object:children-changed:remove</TT
+> event on
+ the desktop.</P
+></DIV
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="CUSTOMIZATION"
+></A
+>Chapter 4. Customized Behavior</H1
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> THIS WILL CHANGE POST V1.0. In particular, the
+ method for setting up event handlers and keyboard/braille
+ bindings will be changed so as to allow for easier customization
+ of these bindings. As such, the information in this chapter is
+ here only for historical purposes.</P
+><P
+>The customized behavior of a script is set up in its
+ constructor. In its constructor, each script is expected to
+ extend/override several fields as illustrated in the following
+ diagram and describe below:</P
+><DIV
+CLASS="FIGURE"
+><A
+NAME="AEN335"
+></A
+><P
+><B
+>Figure 4-1. Orca Script Diagram</B
+></P
+><DIV
+CLASS="MEDIAOBJECT"
+><P
+><IMG
+SRC="script.jpg"></P
+></DIV
+></DIV
+><P
+></P
+><UL
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>listeners</TT
+>: a dictionary where the
+ keys are strings that match AT-SPI event types (e.g.,
+ <TT
+CLASS="LITERAL"
+>focus:</TT
+>,
+ <TT
+CLASS="LITERAL"
+>object:text-caret-moved</TT
+>, etc.), and the
+ values are functions to handle the event. Each function
+ is passed an <TT
+CLASS="LITERAL"
+>Event</TT
+> instance (see the
+ <TT
+CLASS="LITERAL"
+>atspi.py</TT
+> module) as its sole
+ parameter and no return value is expected.</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>keybindings</TT
+>: an instance of
+ <TT
+CLASS="LITERAL"
+>keybindings.KeyBindings</TT
+> (see
+ the <TT
+CLASS="LITERAL"
+>keybindings.py</TT
+> module) that defines
+ the keystrokes the script is interested in.</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>braillebindings</TT
+>: a dictionary where
+ the keys are BrlTTY commands (e.g., <TT
+CLASS="LITERAL"
+>CMD_HWINLT</TT
+>,
+ defined in <TT
+CLASS="LITERAL"
+>braille.py</TT
+>), and the values are
+ <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+> instances.</P
+></LI
+></UL
+><P
+>The constructor for the <TT
+CLASS="LITERAL"
+>Script</TT
+> class,
+ which all scripts should ultimately extend (most will extend the
+ <TT
+CLASS="LITERAL"
+>Script</TT
+> subclass of the <TT
+CLASS="LITERAL"
+>default.py</TT
+>
+ module, which in turn extends
+ <TT
+CLASS="LITERAL"
+>Script</TT
+> class of the <TT
+CLASS="LITERAL"
+>script.py</TT
+>
+ module), sets up empty values for each of
+ these fields. As such, a subclass merely needs to
+ extend/override these fields. Each of these fields is described
+ in more detail in the following sections.</P
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SGEVENTLISTENERS"
+>4.1. Defining Event Listeners</A
+></H2
+><P
+>As described above, the <TT
+CLASS="LITERAL"
+>listeners</TT
+> field
+ is a dictionary where the keys are strings that match AT-SPI
+ event types (e.g., <TT
+CLASS="LITERAL"
+>focus:</TT
+>,
+ <TT
+CLASS="LITERAL"
+>object:text-caret-moved</TT
+>, etc.), and the
+ values are functions to handle the event. A script's
+ constructor can modify/extend this dictionary by merely
+ defining an entry:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>self.listeners["focus:"] = self.onFocus</PRE
+><P
+>In the event there is already an entry in the
+ <TT
+CLASS="LITERAL"
+>listeners</TT
+> dictionary, it will be overridden
+ by the new value.</P
+><P
+>As described previously, the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> will register
+ listeners on behalf of a script, and will notify the script of
+ any events via the script's
+ <TT
+CLASS="LITERAL"
+>processObjectEvent</TT
+> method. The
+ <TT
+CLASS="LITERAL"
+>processObjectEvent</TT
+> method of the top level
+ <TT
+CLASS="LITERAL"
+>Script</TT
+> class examines the
+ <TT
+CLASS="LITERAL"
+>type</TT
+> field of the given
+ <TT
+CLASS="LITERAL"
+>event</TT
+>, calling any matching functions from
+ the <TT
+CLASS="LITERAL"
+>listeners</TT
+> dictionary. As such, it is
+ unlikely that a <TT
+CLASS="LITERAL"
+>Script</TT
+> subclass will ever
+ need to override the <TT
+CLASS="LITERAL"
+>processObjectEvent</TT
+>
+ method. Instead, it merely needs to populate the
+ <TT
+CLASS="LITERAL"
+>listeners</TT
+> dictionary as appropriate.</P
+><P
+>The function for an event listener merely takes an
+ <TT
+CLASS="LITERAL"
+>Event</TT
+> instance (see the
+ <TT
+CLASS="LITERAL"
+>atspi.py</TT
+> module) and does whatever it
+ wants; the return value is ignored. For example, the function
+ definition associated with the above
+ <TT
+CLASS="LITERAL"
+>listeners</TT
+> entry might look like the
+ following, where the <TT
+CLASS="LITERAL"
+>event</TT
+> is described
+ above:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>def onFocus(self, event):
+ """Called whenever an object gets focus.
+
+ Arguments:
+ - event: the Event
+ """
+
+ ...
+ orca.setLocusOfFocus(event, event.source)
+ ...</PRE
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SGINPUTEVENTHANDLERS"
+>4.2. Input Event Handlers</A
+></H2
+><P
+>Before describing how to set up keyboard and braille event
+ handlers, it is import to first understand the
+ <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+>, which is defined in the
+ <TT
+CLASS="LITERAL"
+>input_event.py</TT
+> module.
+ <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+>s serve a purpose of
+ holding a function to call for a particular input event, and a
+ human consumable string that provides a short description of
+ the function's behavior. The main purpose of the
+ <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+> is to provide support for
+ the "learn mode" of Orca. If learn mode is enabled, the input
+ event handler will consume the input event (i.e., return True)
+ and merely speak and braille the human consumable string. If
+ learn mode is not enabled, the input event handler will pass
+ the active script and the input event on to the function,
+ returning the boolean value of the function as indication of
+ whether the event should be consumed by Orca or passed on to
+ the application.</P
+><P
+>The best place to look for examples of
+ <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+>s is in the
+ <TT
+CLASS="LITERAL"
+>default.py</TT
+> module. For example, this
+ module defines an input event handler for telling the flat
+ review context to move to the home position of a
+ window:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>reviewHomeHandler = input_event.InputEventHandler(
+ Script.reviewHome,
+ _("Moves flat review to the home position."))</PRE
+><P
+>In this definition, <TT
+CLASS="LITERAL"
+>default.py</TT
+> is creating
+ an <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+> instance whose function is
+ the Script's method, <TT
+CLASS="LITERAL"
+>reviewHome</TT
+> and whose
+ human consumable text describes what will happen. The Script's
+ <TT
+CLASS="LITERAL"
+>reviewHome</TT
+> method is defined as follows:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>def reviewHome(self, inputEvent):
+ """Moves the flat review context to the top left of the current
+ window."""
+ context = self.getFlatReviewContext()
+ context.goBegin()
+ self.reviewCurrentLine(inputEvent)
+ self.targetCursorCell = braille.cursorCell
+ return True</PRE
+><P
+>Note that the method returns <TT
+CLASS="LITERAL"
+>True</TT
+> to
+ indicate the input event has been consumed.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SGKEYBINDINGS"
+>4.3. Defining Keyboard Bindings</A
+></H2
+><P
+>The keyboard bindings for a script are held in the
+ <TT
+CLASS="LITERAL"
+>keybindings</TT
+> field, which is a
+ <TT
+CLASS="LITERAL"
+>KeyBindings</TT
+> instance. This field maintains
+ a set of <TT
+CLASS="LITERAL"
+>KeyBinding</TT
+> instances.</P
+><P
+>Keyboard bindings merely define the keystroke and modifier
+ circumstances needed to invoke an
+ <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+> instance. This definition
+ is held in a <TT
+CLASS="LITERAL"
+>KeyBinding</TT
+> instance (see the
+ <TT
+CLASS="LITERAL"
+>keybindings.py</TT
+> module):</P
+><PRE
+CLASS="PROGRAMLISTING"
+>self.keybindings.add(
+ keybindings.KeyBinding("KP_7",
+ 1 << orca.MODIFIER_ORCA,
+ 1 << orca.MODIFIER_ORCA,
+ reviewHomeHandler))</PRE
+><P
+>The first parameter of a <TT
+CLASS="LITERAL"
+>KeyBinding</TT
+> is
+ a string that represents an X Window System KeySym string for
+ the key. This is typically a string from
+ <TT
+CLASS="LITERAL"
+>/usr/include/X11/keysymdef.h</TT
+> with the
+ preceding 'XK_' removed (e.g., XK_KP_Enter becomes the string
+ 'KP_Enter'), and is used as a means to express the physical
+ key associated with the KeySym.</P
+><P
+>The second parameter is a bit mask that defines which
+ modifiers the keybinding cares about. If it does not care
+ about any modifier state, then this mask can be set to 0. In
+ the example above, the keybinding is being told to pay
+ attention to the <TT
+CLASS="LITERAL"
+>MODIFIER_ORCA</TT
+> modifier,
+ which is a modifier Orca sets when the "Insert" key is
+ pressed. Other examples of modifier bit positions include
+ those defined in the AT-SPI Accessibility specification:
+ MODIFIER_SHIFT, MODIFIER_SHIFTLOCK, MODIFIER_CONTROL,
+ MODIFIER_ALT, MODIFIER_META, MODIFIER_META2, MODIFIER_META3,
+ and MODIFIER_NUMLOCK. These can be obtained via the
+ <TT
+CLASS="LITERAL"
+>orca.atspi.Accessibility</TT
+> field. For
+ example,
+ <TT
+CLASS="LITERAL"
+>orca.atspi.Accessibility.MODIFIER_SHIFTLOCK</TT
+>.</P
+><P
+>The third parameter is a bit mask that defines what the
+ modifier settings must be. If a bit is set, it means the
+ associated modifier must be set. The only meaningful bits in
+ this mask are those that are defined by the second
+ parameter. In the example above, the keybinding cares
+ about the <TT
+CLASS="LITERAL"
+>MODIFIER_ORCA</TT
+> modifier, and
+ the third parameter says this modifier must be set.</P
+><P
+>The last parameter is the
+ <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+> to us if the user types a
+ keystroke qualified by the previous
+ parameters. <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+>s are
+ described in the previous section.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SGBRAILLEBINDINGS"
+>4.4. Defining Braille Bindings</A
+></H2
+><P
+>Refreshable braille displays have buttons that the user
+ can press. The BrlTTY system provides a means for
+ standardizing the types of input events one can generate using
+ these buttons, and a script can set up braille bindings to
+ handle these events.</P
+><P
+>The braille bindings for a script are held in the
+ <TT
+CLASS="LITERAL"
+>braillebindings</TT
+> field, which is a
+ dictionary. The keys for the dictionary are BrlTTY constants
+ representing braille input events (see
+ <TT
+CLASS="LITERAL"
+>braille.py</TT
+> for a list), and the values are
+ <TT
+CLASS="LITERAL"
+>InputEventHandler</TT
+> instances:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>self.braillebindings[braille.CMD_TOP_LEFT] = reviewHomeHandler</PRE
+><P
+>In the above example, the BrlTTY
+ <TT
+CLASS="LITERAL"
+>braille.CMD_TOP_LEFT</TT
+> input event has been
+ set to be handled by the same
+ <TT
+CLASS="LITERAL"
+>reviewHomeHandler</TT
+> instance described
+ previously.</P
+></DIV
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="SGUTILITIES"
+></A
+>Chapter 5. Script Utilities</H1
+><P
+>There are many common things a script wants to do: generate
+ speech, update braille, etc. In addition, there are many common
+ things a script writer wants to do, especially getting debug
+ output to determine just what the AT-SPI is sending it. This
+ chapter discusses the debug utilities of Orca as well as a
+ variety of utilities to assist a script in managing speech,
+ braille, and magnification.</P
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="DEBUG"
+>5.1. Debug Utilities</A
+></H2
+><P
+>The debug utilities (defined in the
+ <TT
+CLASS="LITERAL"
+>debug.py</TT
+> module) of Orca provide a means
+ for selectively turning on information to be sent to the
+ console where Orca is running. This information is quite
+ useful in determining what is happening inside Orca as well as
+ what the AT-SPI is sending to Orca.</P
+><P
+>Let's begin the discussion of the debug utilities with the
+ top question on any script writer's mind: "What do I name my
+ script?" As you may recall, the name of a script is based
+ upon the name of the application as given to us by the AT-SPI.
+ One of the easy ways to determine this is to listen for
+ <TT
+CLASS="LITERAL"
+>window:activate</TT
+> events that will be issued
+ when an application is started. These events can then be used
+ to determine the name of the application.</P
+><P
+>Fortunately, the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> already registers
+ for <TT
+CLASS="LITERAL"
+>window:activate</TT
+> events, so all you need
+ to do is tell Orca to print these events out when it receives
+ them. The method for doing this involves telling the debug
+ utilities what to do, and this can be done by modifying your
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+>.</P
+><P
+>There are two main settings to tell Orca to print out
+ events: an event filter and an event debug level. The event
+ filter is a regular expression that is used to match AT-SPI
+ event types, and the event debug level specifies a threshold
+ for when to actually print information to the console (for
+ more complete detail on these settings, refer to
+ <TT
+CLASS="LITERAL"
+>debug.py</TT
+>). These settings can be modified
+ by adding the following lines to your
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+>:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>orca.debug.setEventDebugFilter(re.compile('window:activate'))
+orca.debug.setEventDebugLevel(debug.LEVEL_OFF)
+ </PRE
+><P
+>Now, when you rerun Orca, it will output information
+ whenever it receives a <TT
+CLASS="LITERAL"
+>window:activate</TT
+>
+ event from the AT-SPI registry. For example, if you run Star
+ Office, you should see output similar to the following:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>OBJECT EVENT: window:activate detail=(0,0)
+ app='StarOffice' name='StarOffice' role='frame'
+ state='ENABLED FOCUSABLE RESIZABLE SENSITIVE SHOWING VISIBLE'
+ </PRE
+><P
+>The string <TT
+CLASS="LITERAL"
+>app='StarOffice'</TT
+> indicates
+ the name of the application is 'StarOffice.' As such, if you
+ wanted to write a custom script, you would call it
+ <TT
+CLASS="LITERAL"
+>StarOffice.py</TT
+>.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> you can also get other information while Orca is
+ running by pressing the debug keystrokes:</P
+><P
+></P
+><UL
+><LI
+><P
+>Insert+F5: dump a list of all applications to the
+ console</P
+></LI
+><LI
+><P
+>Insert+F6: speak/braille information about the active
+ script and application with focus</P
+></LI
+><LI
+><P
+>Insert+F7: dump the ancestors of the object with focus
+ to the console</P
+></LI
+><LI
+><P
+>Insert+F8: dump the entire widget hierarchy of the
+ application with focus to the console</P
+></LI
+></UL
+><P
+>The debug module also includes a number of other methods,
+ each of which is described in more detail in
+ <TT
+CLASS="LITERAL"
+>debug.py</TT
+>. Note that each method includes a
+ debug level threshold. The <TT
+CLASS="LITERAL"
+>debug.py</TT
+> module
+ has a description of various level settings and what to expect
+ for output.</P
+><P
+></P
+><UL
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>setDebugLevel(newLevel)</TT
+>: sets the
+ debug level threshold, turning on or off the various debug
+ code built in to the various Orca modules. This is
+ typically called from
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+>.</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>setEventDebugLevel(newLevel)</TT
+>:
+ described above; typically called from
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+>.</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>setEventDebugFilter(regExpression)</TT
+>:
+ described above; typically called from
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+>.</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>printException(level)</TT
+>: if an
+ exception is caught, this can be used to print out detail
+ about it</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>printStack(level)</TT
+>: prints the
+ current stack; useful for determining when and why a code
+ path is being executed</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>println(level, text)</TT
+>: prints the
+ given text; useful for general debug output</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>printObjectEvent(level, event)</TT
+>:
+ prints out the given AT-SPI event</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>printObjectEvent(level, event)</TT
+>:
+ prints out the given AT-SPI event, using the event debug
+ level as an additional threshold; this is already used by
+ the <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>, so you
+ are unlikely to need it</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>printInputEvent(level, string)</TT
+>:
+ prints out the given AT-SPI event, using the event debug
+ level as an additional threshold; this is already used by
+ <TT
+CLASS="LITERAL"
+>orca.py</TT
+> (for keyboard events) and
+ <TT
+CLASS="LITERAL"
+>braille.py</TT
+> (for braille events), so you
+ are unlikely to need it</P
+></LI
+></UL
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> One debug level of interest is
+ <TT
+CLASS="LITERAL"
+>debug.LEVEL_FINE</TT
+>. This level will tell you
+ when a script is activated, and can be useful to determine if
+ Orca is actually finding your script! For example, when the
+ script for the <TT
+CLASS="LITERAL"
+>gnome-terminal</TT
+> is activated
+ by the <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+>, you will
+ see the following output:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>ACTIVE SCRIPT: gnome-terminal (module=orca.scripts.gnome-terminal)
+ </PRE
+><P
+>Notice that the class of the script instance is included.
+ If you determine that this class is not what you expect when
+ you are developing your custom script, then something went
+ wrong when trying to find or load your custom script. This
+ can often happen because Python performs a lot of late binding
+ and compilation, thus errors are often not encountered until a
+ specific code path is executed at run time. You can tell the
+ <TT
+CLASS="LITERAL"
+>focus_tracking_presenter</TT
+> to give you more
+ information about any possible failures or exceptions it
+ handles in this area by setting the debug level to
+ <TT
+CLASS="LITERAL"
+>debug.LEVEL_FINEST</TT
+>.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SGTTS"
+>5.2. Speech Synthesis</A
+></H2
+><P
+>Orca provides two main modules for speech output:
+ <TT
+CLASS="LITERAL"
+>speech.py</TT
+> and
+ <TT
+CLASS="LITERAL"
+>speechgenerator.py</TT
+>. The
+ <TT
+CLASS="LITERAL"
+>speech.py</TT
+> module provides the main interface
+ to the speech synthesis subsystem. The
+ <TT
+CLASS="LITERAL"
+>speechgenerator.py</TT
+> module provides a
+ <TT
+CLASS="LITERAL"
+>SpeechGenerator</TT
+> class that can be used to to
+ actually generate the text to be spoken for various objects.
+ The expected use of the two modules is as follows: a script will
+ create its own instance of a
+ <TT
+CLASS="LITERAL"
+>SpeechGenerator</TT
+> and will use it to generate
+ text. The script will then pass this text to the
+ <TT
+CLASS="LITERAL"
+>speech.py</TT
+> module to be spoken.</P
+><DIV
+CLASS="SECTION"
+><HR><H3
+CLASS="SECTION"
+><A
+NAME="SGSPEECHPY"
+>5.2.1. <TT
+CLASS="LITERAL"
+>speech.py</TT
+></A
+></H3
+><P
+>For the purposes of script writing, the main entry
+ points of the <TT
+CLASS="LITERAL"
+>speech.py</TT
+> module are
+ <TT
+CLASS="LITERAL"
+>speak</TT
+>,
+ <TT
+CLASS="LITERAL"
+>speakUtterances</TT
+>, and
+ <TT
+CLASS="LITERAL"
+>stop</TT
+></P
+><P
+>See the <TT
+CLASS="LITERAL"
+>speech.py</TT
+> module for more
+ information.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H3
+CLASS="SECTION"
+><A
+NAME="SGSGPY"
+>5.2.2. <TT
+CLASS="LITERAL"
+>speechgenerator.py</TT
+></A
+></H3
+><P
+>The primary goal of a <TT
+CLASS="LITERAL"
+>SpeechGenerator</TT
+>
+ is to create text to be spoken for an accessible object.
+ There are two public entry points into a
+ <TT
+CLASS="LITERAL"
+>SpeechGenerator</TT
+>:</P
+><P
+></P
+><UL
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>getSpeech(obj, already_focused)</TT
+>:
+ returns a list of strings to be spoken
+ for the given accessible object. The
+ <TT
+CLASS="LITERAL"
+>already_focused</TT
+> boolean parameter
+ provides a hint to the speech generator about how much
+ text to generate. For example, if a check box that
+ already has focus is to be spoken, usually the reason
+ for this is that the state changed between checked and
+ unchecked. As a result, an appropriate thing to do in
+ this situation is to only speak the new change in
+ state (e.g., "checked").</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>getSpeechContext(obj,
+ stopAncestor)</TT
+>: returns a list
+ of strings to be spoken that describe the visual context
+ of the given accessible object. This is loosely
+ represented by the hierarchical relationship of the
+ object (i.e., the "Quit" button in the "File" menu in
+ the ...), and the amount of information can be contained
+ by specifying an accessible
+ <TT
+CLASS="LITERAL"
+>stopAncestor</TT
+> above which we do not
+ want to know anything about. The primary use of this
+ method is to provide the user with feedback regarding
+ the relevant visual context information that changed
+ when the locus of focus changes, but this method is also
+ useful for assisting in "where am I" queries.</P
+></LI
+></UL
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> Orca currently provides some level of support for
+ verbosity via the <TT
+CLASS="LITERAL"
+>VERBOSITY_LEVEL</TT
+> fields
+ of the <TT
+CLASS="LITERAL"
+>settings.py</TT
+> module. There are
+ currently two verbosity levels:
+ <TT
+CLASS="LITERAL"
+>VERBOSITY_LEVEL_BRIEF</TT
+> and
+ <TT
+CLASS="LITERAL"
+>VERBOSITY_LEVEL_VERBOSE</TT
+>. A
+ <TT
+CLASS="LITERAL"
+>SpeechGenerator</TT
+> subclass is expected to
+ examine the <TT
+CLASS="LITERAL"
+>speechVerbosityLevel</TT
+> property
+ of the <TT
+CLASS="LITERAL"
+>settings.py</TT
+> module and provide the
+ appropriate level of text:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>if settings.speechVerbosityLevel == settings.VERBOSITY_LEVEL_VERBOSE:
+ utterances.append(rolenames.getSpeechForRoleName(obj))
+ </PRE
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="SGBRAILLEOUTPUT"
+>5.3. Braille Output</A
+></H2
+><P
+>Like speech, Orca provides two main modules for braille:
+ <TT
+CLASS="LITERAL"
+>braille.py</TT
+> and
+ <TT
+CLASS="LITERAL"
+>braillegenerator.py</TT
+>. The
+ <TT
+CLASS="LITERAL"
+>braille.py</TT
+> module provides the main interface
+ to the braille display. The
+ <TT
+CLASS="LITERAL"
+>braillegenerator.py</TT
+> module provides a
+ <TT
+CLASS="LITERAL"
+>BrailleGenerator</TT
+> class that can be used to to
+ actually generate the text to be displayed for various objects.
+ The expected use of the two modules is as follows: a script will
+ create its own instance of a
+ <TT
+CLASS="LITERAL"
+>BrailleGenerator</TT
+> and will use it to braille
+ regions. The script will then pass these braille regions to the
+ <TT
+CLASS="LITERAL"
+>braille.py</TT
+> module to be displayed.</P
+><DIV
+CLASS="SECTION"
+><HR><H3
+CLASS="SECTION"
+><A
+NAME="SGBRAILLEPY"
+>5.3.1. <TT
+CLASS="LITERAL"
+>braille.py</TT
+></A
+></H3
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>TODO:</I
+></SPAN
+> [[[WDW - much writing to be done here, especially
+ regarding how regions will provide automatic support for
+ cursor routing keys.]]]</P
+></DIV
+><DIV
+CLASS="SECTION"
+><HR><H3
+CLASS="SECTION"
+><A
+NAME="SGBGPY"
+>5.3.2. <TT
+CLASS="LITERAL"
+>braillegenerator.py</TT
+></A
+></H3
+><P
+>The primary goal of a <TT
+CLASS="LITERAL"
+>BrailleGenerator</TT
+>
+ is to create text to be displayed for an accessible object.
+ There are two public entry points into a
+ <TT
+CLASS="LITERAL"
+>BrailleGenerator</TT
+>:</P
+><P
+></P
+><UL
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>getBrailleRegions(obj,
+ groupChildren=True)</TT
+>: returns a list of two
+ items: the first is an ordered list of braille
+ <TT
+CLASS="LITERAL"
+>Region</TT
+> instances that represent text
+ to be displayed on the braille display, left-to-right on
+ one line; and the second is an element from the first
+ list that represents which <TT
+CLASS="LITERAL"
+>Region</TT
+> has
+ "focus" and should be represented by the braille cursor
+ on the display.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>TODO:</I
+></SPAN
+> [[[WDW - describe grouping of children.]]]</P
+></LI
+><LI
+><P
+><TT
+CLASS="LITERAL"
+>getBrailleContext(obj)</TT
+>: returns
+ an ordered list (i.e., an array) of braille
+ <TT
+CLASS="LITERAL"
+>Region</TT
+> instances that describe the
+ visual context of the given accessible object. This is
+ loosely represented by the hierarchical relationship of
+ the object (i.e., the "Quit" button in the "File" menu
+ in the ...).</P
+></LI
+></UL
+><P
+>Typically, a script will "build up" a single logical
+ line of text for the braille display. The beginning of this
+ line will be the result of the call to
+ <TT
+CLASS="LITERAL"
+>getBrailleContext</TT
+> and the remainder of
+ the line will be the result of one or more calls to
+ <TT
+CLASS="LITERAL"
+>getBrailleRegions</TT
+>. Since the logical
+ line will typically be longer than the number of cells on
+ the braille display, the <TT
+CLASS="LITERAL"
+>braille.py</TT
+>
+ module will scroll to show the braille
+ <TT
+CLASS="LITERAL"
+>Region</TT
+> with focus. Furthermore, the
+ <TT
+CLASS="LITERAL"
+>braille.py</TT
+> will also respond to BrlTTY
+ input events to allow the user to use braille display input
+ buttons for scrolling to review the entire line.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> Orca currently provides some level of support for
+ verbosity via the <TT
+CLASS="LITERAL"
+>VERBOSITY_LEVEL</TT
+> fields
+ of the <TT
+CLASS="LITERAL"
+>settings.py</TT
+> module. There are
+ currently two verbosity levels:
+ <TT
+CLASS="LITERAL"
+>VERBOSITY_LEVEL_BRIEF</TT
+> and
+ <TT
+CLASS="LITERAL"
+>VERBOSITY_LEVEL_VERBOSE</TT
+>. A
+ <TT
+CLASS="LITERAL"
+>BrailleGenerator</TT
+> subclass is expected to
+ examine the <TT
+CLASS="LITERAL"
+>brailleVerbosityLevel</TT
+> property
+ of the <TT
+CLASS="LITERAL"
+>settings.py</TT
+> module and provide the
+ appropriate level of text:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>if settings.brailleVerbosityLevel == settings.VERBOSITY_LEVEL_VERBOSE:
+ regions.append(braille.Region(
+ " " + rolenames.getBrailleForRoleName(obj)))
+ </PRE
+></DIV
+></DIV
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="I18N"
+></A
+>Chapter 6. Internationalization (I18N) Support</H1
+><P
+>All human-consumable text obtained from AT-SPI calls is
+ expected to be in a localized form. As such, Orca does not
+ do any extra localization processing when working with text
+ obtained via the AT-SPI.</P
+><P
+>For text generated by Orca itself, Orca handles
+ internationalization and localization using the [<SPAN
+CLASS="CITATION"
+><A
+HREF="#GETTEXT"
+><I
+>gettext</I
+></A
+>></SPAN
+>] support
+ of Python. The gettext support of Python is similar to the GNU
+ gettext module. Each human consumable string of Orca is US
+ English text wrapped in a call to gettext.gettext. The call to
+ gettext.gettext will either return a localized string or default
+ to the US English text. Orca depends upon an active and thriving
+ community of open source translators to provide the
+ localizations.</P
+><P
+>The synthesis of localized speech is to be provided by the
+ underlying gnome-speech engine. That is, Orca merely passes
+ localized text to the speech engine, which is responsible for
+ the correct interpretation and pronunciation.</P
+><P
+>The generation of localized braille is to be determined.
+ <SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>TODO:</I
+></SPAN
+> BrlTTY currently does not support this at the moment, but
+ it is expected that the BrlTTY developers will add this in the
+ future.</P
+></DIV
+><A
+NAME="ARCHBIBLIOGRAPHY"
+></A
+><HR><H1
+><A
+NAME="ARCHBIBLIOGRAPHY"
+></A
+>Bibliography</H1
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="AT-SPI"
+></A
+><P
+>[AT-SPI] <SPAN
+CLASS="AUTHOR"
+>Bill Haneman, </SPAN
+><SPAN
+CLASS="AUTHOR"
+>Marc Mulcahy, </SPAN
+><SPAN
+CLASS="AUTHOR"
+>and Michael Meeks</SPAN
+>, <I
+><A
+HREF="http://directory.fsf.org/accessibility/at-spi.html";
+TARGET="_top"
+> AT-SPI</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="ACSS"
+></A
+><P
+>[ACSS] <SPAN
+CLASS="AUTHOR"
+>T.V. Raman</SPAN
+>, <I
+><A
+HREF="http://www.w3.org/TR/1998/REC-CSS2-19980512/aural.html";
+TARGET="_top"
+>Aural Style Sheets</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="BONOBO"
+></A
+><P
+>[Bonobo] <SPAN
+CLASS="AUTHOR"
+>George Lebl</SPAN
+>, <I
+><A
+HREF="http://lidn.sourceforge.net/articles/gnomenclatureintrotobonobo/";
+TARGET="_top"
+> Gnomenclature: Intro to bonobo</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="BRLTTY"
+></A
+><P
+>[BRLTTY] <SPAN
+CLASS="AUTHOR"
+>Dave Meilke, </SPAN
+><SPAN
+CLASS="AUTHOR"
+>Nicolas Pitre, </SPAN
+><SPAN
+CLASS="AUTHOR"
+>and Stephane Doyon</SPAN
+>, <I
+><A
+HREF="http://directory.fsf.org/accessibility/brltty.html";
+TARGET="_top"
+> BRLTTY</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="EMACSPEAK"
+></A
+><P
+>[Emacspeak] <SPAN
+CLASS="AUTHOR"
+>T.V. Raman</SPAN
+>, <I
+><A
+HREF="http://emacspeak.sourceforge.net/";
+TARGET="_top"
+>Emacspeak</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="GAIL"
+></A
+><P
+>[GAIL] <SPAN
+CLASS="AUTHOR"
+>Bill Haneman</SPAN
+>, <I
+><A
+HREF="http://freshmeat.net/projects/gail/";
+TARGET="_top"
+> GAIL</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="GETTEXT"
+></A
+><P
+>[gettext] <SPAN
+CLASS="AUTHOR"
+>TODO: Unknown</SPAN
+>, <I
+><A
+HREF="http://docs.python.org/lib/module-gettext.html";
+TARGET="_top"
+> gettext</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="GNOME-MAG"
+></A
+><P
+>[gnome-mag] <SPAN
+CLASS="AUTHOR"
+>Bill Haneman</SPAN
+>, <I
+><A
+HREF="http://directory.fsf.org/accessibility/gnome-mag.html";
+TARGET="_top"
+> gnome-mag</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="GNOME-SPEECH"
+></A
+><P
+>[gnome-speech] <SPAN
+CLASS="AUTHOR"
+>Marc Mulcahy </SPAN
+><SPAN
+CLASS="AUTHOR"
+>and Michael Meeks</SPAN
+>, <I
+><A
+HREF="http://directory.fsf.org/accessibility/gnome-speech.html";
+TARGET="_top"
+> gnome-speech</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="GNOPERNICUS"
+></A
+><P
+>[Gnopernicus] <SPAN
+CLASS="AUTHOR"
+>Remus Draica</SPAN
+>, <I
+><A
+HREF="http://directory.fsf.org/accessibility/gnopernicus.html";
+TARGET="_top"
+> Gnopernicus</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="JAWS"
+></A
+><P
+>[JAWS] <SPAN
+CLASS="AUTHOR"
+> Freedom Scientific</SPAN
+>, <I
+><A
+HREF="http://www.freedomscientific.com/fsproducts/softwarejaws.asp";
+TARGET="_top"
+> JAWS</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+><DIV
+CLASS="BIBLIOENTRY"
+><A
+NAME="XKB"
+></A
+><P
+>[XKB] <SPAN
+CLASS="AUTHOR"
+>Erik Fortune, </SPAN
+><SPAN
+CLASS="AUTHOR"
+>William Walker, </SPAN
+><SPAN
+CLASS="AUTHOR"
+>Donna Converse, </SPAN
+><SPAN
+CLASS="AUTHOR"
+>and George Sachs</SPAN
+>, <I
+><A
+HREF="http://matrix.netsoc.tcd.ie/hcksplat/work/XKBlib.pdf";
+TARGET="_top"
+> The XKB keyboard extension</A
+>
+ </I
+>.</P
+><DIV
+CLASS="BIBLIOENTRYBLOCK"
+STYLE="margin-left: 0.5in"
+></DIV
+></DIV
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
Added: trunk/docs/doc-set/internals.pdf
==============================================================================
Binary file. No diff available.
Added: trunk/docs/doc-set/user_guide.html
==============================================================================
--- (empty file)
+++ trunk/docs/doc-set/user_guide.html Wed Jun 25 15:49:19 2008
@@ -0,0 +1,519 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd";>
+<HTML
+><HEAD
+><TITLE
+>Orca User's Guide</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
+><BODY
+CLASS="BOOK"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="BOOK"
+><A
+NAME="USERGUIDE"
+></A
+><DIV
+CLASS="TITLEPAGE"
+><H1
+CLASS="TITLE"
+><A
+NAME="USERGUIDE"
+>Orca User's Guide</A
+></H1
+><DIV
+CLASS="LEGALNOTICE"
+><P
+></P
+><A
+NAME="AEN4"
+></A
+><P
+>Copyright 2005-2008, Sun Microsystems, Inc.</P
+><P
+></P
+></DIV
+><HR></DIV
+><DIV
+CLASS="TOC"
+><DL
+><DT
+><B
+>Table of Contents</B
+></DT
+><DT
+><A
+HREF="#UGFORWARD"
+>Foreword</A
+></DT
+><DT
+>1. <A
+HREF="#UGINTRODUCTION"
+>Introduction</A
+></DT
+><DT
+>2. <A
+HREF="#UGRUNNING"
+>Running Orca</A
+></DT
+><DT
+>3. <A
+HREF="#UGCUSTOMIZATION"
+>Customizing Orca</A
+></DT
+><DD
+><DL
+><DT
+>3.1. <A
+HREF="#UGMODKEYS"
+><TT
+CLASS="LITERAL"
+>orcaModifierKeys</TT
+> - Override "Insert" as Orca Modifier Key</A
+></DT
+></DL
+></DD
+></DL
+></DIV
+><DIV
+CLASS="PREFACE"
+><HR><H1
+><A
+NAME="UGFORWARD"
+></A
+>Foreword</H1
+><P
+>Orca is a flexible, extensible, and powerful assistive
+ technology that provides end-user access to applications and
+ toolkits that support the AT-SPI (e.g., the GNOME desktop). With
+ early input from and continued engagement with its end users, Orca
+ has been designed and implemented by the Sun Microsystems, Inc.,
+ Accessibility Program Office.</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> Orca is currently a work in progress. As a result, this
+ and other books in the Orca Documentation Series are under
+ continuous modification and are also in various states of
+ completeness.</P
+><P
+>This book provides a guide for the installation, configuration
+ and use of Orca. It also includes details on how users can customize
+ the keyboard and braille input mappings of Orca.
+ </P
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="UGINTRODUCTION"
+></A
+>Chapter 1. Introduction</H1
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>TODO:</I
+></SPAN
+> To be written. This currently contains just the most
+ important stuff you need to know. In addition, you should always
+ visit <A
+HREF="http://live.gnome.org/Orca";
+TARGET="_top"
+> http://live.gnome.org/Orca</A
+> for the
+ latest information and hints on using Orca.</P
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="UGRUNNING"
+></A
+>Chapter 2. Running Orca</H1
+><P
+>You can run Orca in many ways:</P
+><P
+></P
+><UL
+><LI
+><P
+>Using the <TT
+CLASS="LITERAL"
+>orca</TT
+> command from a terminal
+ or virtual console. For many users, this is the easiest and
+ most accessible way to launch Orca.</P
+></LI
+><LI
+><P
+>Via the "Run Application" dialog that you can bring up
+ by pressing <TT
+CLASS="LITERAL"
+>Alt+F2</TT
+>. In this dialog, type
+ <TT
+CLASS="LITERAL"
+>orca</TT
+> and press
+ <TT
+CLASS="LITERAL"
+>Return</TT
+>.</P
+></LI
+><LI
+><P
+>Via the "Orca Screen Reader and Magnifier" menu item
+ available from the "Accessibility" submenu off of the
+ "Applications" menu on some systems.</P
+></LI
+><LI
+><P
+>For GNOME 2.16 and later, via the "Assistive Technology
+ Support" preferences dialog that you can launch from the
+ "Preferences" menu on some systems. This will enable
+ accessibility in your environment and tell Orca to
+ automatically launch when you log in.</P
+></LI
+><LI
+><P
+>Via the "Startup Programs" tab in the "Sessions" dialog
+ that you can launch from the "Preferences" menu on some
+ systems. This will automatically launch Orca when you
+ log in if you add <TT
+CLASS="LITERAL"
+>orca</TT
+> as a startup
+ program.</P
+></LI
+></UL
+><P
+>When you run the <TT
+CLASS="LITERAL"
+>orca</TT
+> command from a
+ terminal window, you have the following options:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>Usage: orca [OPTION...]
+
+-?, --help Show this help message
+-v, --version 0.9.0
+-s, --setup, --gui-setup Set up user preferences
+-t, --text-setup Set up user preferences (text version)
+-n, --no-setup Skip set up of user preferences
+
+If Orca has not been previously set up by the user, Orca
+will automatically launch the preferences set up unless
+the -n or --no-setup option is used.
+
+Report bugs to orca-list gnome org
+ </PRE
+><P
+>If you have not run Orca before, it will automatically query
+ you for preferences, such as whether you want to use speech,
+ braille, or magnification. These preferences are saved in
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+> (see material in
+ the following sections for more information).</P
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> The GNOME accessibility environment requires
+ accessibility to be enabled for your login session, which is not
+ the default configuration. The first time you run Orca, Orca
+ will detect this and will enable accessibility for you. In
+ order for this to take effect, however, you still need to log
+ out and log back in.</P
+><P
+>To get help while running Orca, you can press
+ <TT
+CLASS="LITERAL"
+>Insert+F1</TT
+> to enter learn mode. In learn
+ mode, you can type any key combination and Orca will tell you
+ the effects of that key combination. To exit learn mode, press
+ <TT
+CLASS="LITERAL"
+>Escape</TT
+>.</P
+><P
+>To quit Orca, you can do any of the following:</P
+><P
+></P
+><UL
+><LI
+><P
+>Press <TT
+CLASS="LITERAL"
+>Insert+Q</TT
+></P
+></LI
+><LI
+><P
+>Enter <TT
+CLASS="LITERAL"
+>killall -TERM orca</TT
+> in a
+ terminal window. <SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> if you enter <TT
+CLASS="LITERAL"
+>killall -HUP
+ orca</TT
+> in a terminal window, Orca will restart.</P
+></LI
+></UL
+><P
+><SPAN
+CLASS="emphasis"
+><I
+CLASS="EMPHASIS"
+>NOTE:</I
+></SPAN
+> the main shell script to start Orca,
+ <TT
+CLASS="LITERAL"
+>/usr/bin/orca</TT
+>, will detect failures in Orca
+ and restart it if necessary. In addition, it will stop any
+ existing Orca-related processes before starting Orca again.
+ As such, if something bad seems to have happened with Orca,
+ you can force it to clean up and restart by merely launching
+ Orca again via any of the methods listed previously.</P
+></DIV
+><DIV
+CLASS="CHAPTER"
+><HR><H1
+><A
+NAME="UGCUSTOMIZATION"
+></A
+>Chapter 3. Customizing Orca</H1
+><P
+>To be written. Include verbosity, speech rate, braille,
+ braille monitor, orca modifier keys, voices, key/word echo, read
+ table line, etc.</P
+><P
+>To configure Orca, you can do any of the following:</P
+><P
+></P
+><UL
+><LI
+><P
+>Run <TT
+CLASS="LITERAL"
+>orca --setup</TT
+></P
+></LI
+><LI
+><P
+>Press <TT
+CLASS="LITERAL"
+>Insert+Space</TT
+> while Orca is
+ running</P
+></LI
+></UL
+><P
+>When you configure Orca, it will create
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+>. You can edit this
+ file using a text editor, but be aware that it will be
+ overwritten the next time you configure Orca. If you wish to
+ have more persistent settings for Orca, you can create
+ <TT
+CLASS="LITERAL"
+>~/.orca/orca-customizations.py</TT
+>. If this file
+ exists (you need to create it if you want one),
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+> will import it each
+ time the settings are reloaded. You can force Orca to reload
+ the settings by pressing
+ <TT
+CLASS="LITERAL"
+>Ctrl+Insert+Space</TT
+>.</P
+><P
+>The contents of a typical
+ <TT
+CLASS="LITERAL"
+>~/.orca/user-settings.py</TT
+> look similar to the
+ following:</P
+><PRE
+CLASS="PROGRAMLISTING"
+># user-settings.py - custom Orca settings
+# Generated by orca. DO NOT EDIT THIS FILE!!!
+# If you want permanent customizations that will not
+# be overwritten, edit orca-customizations.py.
+#
+import re
+import time
+
+import orca.debug
+import orca.settings
+import orca.acss
+
+#orca.debug.debugLevel = orca.debug.LEVEL_OFF
+orca.debug.debugLevel = orca.debug.LEVEL_SEVERE
+#orca.debug.debugLevel = orca.debug.LEVEL_WARNING
+#orca.debug.debugLevel = orca.debug.LEVEL_INFO
+#orca.debug.debugLevel = orca.debug.LEVEL_CONFIGURATION
+#orca.debug.debugLevel = orca.debug.LEVEL_FINE
+#orca.debug.debugLevel = orca.debug.LEVEL_FINER
+#orca.debug.debugLevel = orca.debug.LEVEL_FINEST
+#orca.debug.debugLevel = orca.debug.LEVEL_ALL
+
+#orca.debug.eventDebugLevel = orca.debug.LEVEL_OFF
+#orca.debug.eventDebugFilter = None
+#orca.debug.eventDebugFilter = re.compile('[\S]*focus|[\S]*activ')
+#orca.debug.eventDebugFilter = re.compile('nomatch')
+#orca.debug.eventDebugFilter = re.compile('[\S]*:accessible-name')
+
+#orca.debug.debugFile = open(time.strftime('debug-%Y-%m-%d-%H:%M:%S.out'), 'w', 0)
+#orca.debug.debugFile = open('debug.out', 'w', 0)
+
+#orca.settings.useBonoboMain=False
+#orca.settings.debugEventQueue=True
+#orca.settings.gilSleepTime=0
+
+if False:
+ import sys
+ import orca.util
+ sys.settrace(orca.util.traceit)
+ orca.debug.debugLevel = orca.debug.LEVEL_ALL
+
+orca.settings.orcaModifierKeys = ['Insert', 'KP_Insert']
+orca.settings.enableSpeech = True
+orca.settings.speechServerFactory = 'orca.gnomespeechfactory'
+orca.settings.speechServerInfo = ['Fonix DECtalk GNOME Speech Driver', 'OAFIID:GNOME_Speech_SynthesisDriver_Dectalk:proto0.3']
+orca.settings.voices = {
+'default' : orca.acss.ACSS({'average-pitch': 5.0,
+ 'family': {'locale': 'english', 'gender': None, 'name': 'Paul'},
+ 'gain': 9,
+ 'rate': 85.0}),
+'uppercase' : orca.acss.ACSS({'average-pitch': 6}),
+'hyperlink' : orca.acss.ACSS({'average-pitch': 2}),
+}
+orca.settings.speechVerbosityLevel = orca.settings.VERBOSITY_LEVEL_VERBOSE
+orca.settings.readTableCellRow = True
+orca.settings.enableSpeechIndentation = False
+orca.settings.enableEchoByWord = True
+orca.settings.enableKeyEcho = True
+orca.settings.enablePrintableKeys = False
+orca.settings.enableModifierKeys = False
+orca.settings.enableLockingKeys = True
+orca.settings.enableFunctionKeys = False
+orca.settings.enableActionKeys = False
+orca.settings.enableBraille = False
+orca.settings.enableBrailleGrouping = False
+orca.settings.brailleVerbosityLevel = orca.settings.VERBOSITY_LEVEL_VERBOSE
+orca.settings.brailleRolenameStyle = orca.settings.BRAILLE_ROLENAME_STYLE_LONG
+orca.settings.enableBrailleMonitor = False
+orca.settings.enableMagnifier = False
+orca.settings.enableMagCursor = True
+orca.settings.enableMagCursorExplicitSize = False
+orca.settings.magCursorSize = 32
+orca.settings.magCursorColor = '#000000'
+orca.settings.enableMagCrossHair = True
+orca.settings.enableMagCrossHairClip = False
+orca.settings.magCrossHairSize = 16
+orca.settings.magZoomerLeft = 512
+orca.settings.magZoomerRight = 1014
+orca.settings.magZoomerTop = 0
+orca.settings.magZoomerBottom = 758
+orca.settings.magZoomFactor = 4
+orca.settings.enableMagZoomerColorInversion = False
+orca.settings.magSmoothingMode = orca.settings.MAG_SMOOTHING_MODE_BILINEAR
+orca.settings.magMouseTrackingMode = orca.settings.MAG_MOUSE_TRACKING_MODE_CENTERED
+orca.settings.verbalizePunctuationStyle = orca.settings.PUNCTUATION_STYLE_MOST
+
+try:
+ __import__("orca-customizations")
+except ImportError:
+ pass</PRE
+><DIV
+CLASS="SECTION"
+><HR><H2
+CLASS="SECTION"
+><A
+NAME="UGMODKEYS"
+>3.1. <TT
+CLASS="LITERAL"
+>orcaModifierKeys</TT
+> - Override "Insert" as Orca Modifier Key</A
+></H2
+><P
+>Orca defines keystrokes for the
+ keypad and also makes special used of the
+ <TT
+CLASS="LITERAL"
+>Insert</TT
+> key as the Orca modifier key. Orca
+ also provides an <TT
+CLASS="LITERAL"
+>orcaModifierKeys</TT
+>
+ customization setting to allow the user to override
+ <TT
+CLASS="LITERAL"
+>Insert</TT
+> as the Orca modifier key. This
+ setting contains a list of key strings that represent the key
+ to be used as the Orca modifier key. For example, the
+ following example specifies that the keyboard
+ <TT
+CLASS="LITERAL"
+>Insert</TT
+> key (typically near the
+ <TT
+CLASS="LITERAL"
+>Delete</TT
+> key) and the keypad
+ <TT
+CLASS="LITERAL"
+>Insert</TT
+> key (typically the 0 key) are to
+ both act as the Orca modifier key:</P
+><PRE
+CLASS="PROGRAMLISTING"
+>
+orca.settings.orcaModifierKeys = ["Insert", "KP_Insert"] </PRE
+><P
+>You can override this setting in your
+ <TT
+CLASS="LITERAL"
+>~/.orca/orca-customizations.py</TT
+> module if
+ you wish.</P
+></DIV
+></DIV
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
Added: trunk/docs/doc-set/user_guide.pdf
==============================================================================
Binary file. No diff available.
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
