Proposal of OpenOffice.org document representation guide lines.

[Andre Fischer <Andre W Fischer Sun Com>]

Hello,

My name is Andre Fischer.  I am working for Sun Microsystems on making
StarOffice/OpenOffice.org accessible.  We are currently aiming at using the
Java Accessibility API but also have a close look at the Gnome Accessibility
API.  For more information please have look at our Accessibility home page at
http://ui.openoffice.org/accessibility/index.html .

As recommended by Bill Haneman I re-post in the following a proposal that has
already been posted to our OpenOffice.org accessibility mailing list
dev ui openoffice org:

I would like to make the following proposal of guide lines regarding the
representation of documents by the Java/Gnome/UNO Accessibility APIs.  With
this proposal I am trying to start a discussion that will eventually close the
gap in the Java and Gnome Accessible API documentation regarding semantics and
philosphy of document representation.


1: The document representation should be as close to the existing
   visible representation as possible.

Reason: This close correlation enables users of the different document 
        representations to work together on the same document and on 
        the same machine.



2: We should--at least in the first step--only provide information that
   existing AT uses.

Reason: AT vendors will not invest much time and money into supporting an
        API that differs greatly from their current source of information.



3: Use a page based approach.

In case of the Writer, a page based approach would lead to the following:
a) Text is split into lines, possibly with hyphenated words.
   Wether to represent each line by one AccessibleText object or have (parts
   of) paragraphs as smallest units is another question and depends on the 
   extension of the AccessibleText interface to cover line by based text 
   access.
b) Inclusion of items such as page headers and footers as well as footnotes.
c) Possibly more than one text column.
Calc is covered by its own API interface.
Draw and Impress are already page based.

Reason A: This reflects how a document is represented by the GUI.
Reason B: This reflects the final result of using office applications: the
          printed page.
Reason C: It allows the use of a simple and shallow tree structure for
          representing (a part of) a document.



4: Do not represent page items that are completely off-screen.

Remark: It is possible that page items of more than one page are represented 
        at the same time.

Reason: This again keeps the API representation close to the GUI.



5: Don't show hidden objects.

Reason: No visual representation - no API representation.



6: Mark partially visible objects as partially visible if they are atomic or
   split them into their on-screen and off-screen parts if they are not.
   
Reason A: Again consistency with the visual representation.
Reason B: Less objects in the API representation leads to less overhead in the
          case that a whole page has changed and thus all Accessible objects
          become invalid and have to be replaced by new ones.

6a: A whole calc table is not atomic, but its cells are.
    Therefore represent only the completely or partially visible cells.

6b: Text paragraphs can be split between lines (horizontal cut) but not inside
    lines (vertical cut).

Reason: Cutting text horizontally between lines is already done, for example
        when a paragraph does not fit completely on a page.  Cutting inside 
        words and showing of only the first or last parts of lines in contrast
        does not seem to make much sense.

Consequence A: This needs a new state 'Partially visible' in the API.

Consequence B: When the user scrolls the page up/down/wherever throw events
               that inform the user of either that the whole page has changed
               or that some objects are valid anymore and that others have
               been created.



7: Do not represent the cursor position explicitly beyond the means
   of AccessibleText.

Reason: The cursor position, i.e. the position at which text typed on the
        keyboard will be inserted into a document, is maintained either
        completely or, more likely, in part by the AT.  This is done by
        receiving one event with every change of the cursor position, which
        contains information of the AccessibleText object which contains the
        cursor.  This object can then be queried for the caret position.


        
I am looking forward to a constructive discusssion,
Andre