content/ui/accessibility/docrep-guidelines.html - openoffice-org - Git at Google

 <html><head>
 <meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
 </head>
 <body>
 <h2>Document representation guidelines</h2>

 <p><em>Last modification on October 31st 2001.</em></p>

 <p>The following list contains a set of guidelines for the representation of
 StarOffice/OpenOffice.org documents with the UNO Accessibility API (UAA).
 The intention of these guidelines is to define--in an application unspecific
 way--what kind of information of a document should expose over the UAA.  It
 thus complements the syntactic specification made by the actual UAA
 definition.</p>

 <p>It is not the goal of these guidelines to give a detailed description of
 how to represent documents of the individual applications.  That is done at
 another place.
 </p>

 <ol>
 <li><b>View based approach</b><br>
 <p>In order to let people that use different interfaces--for example the
 OpenOffice.org GUI or a Braille display--help each other with working on a
 document all of them need to have access to an <em>equivalent</em>
 representation of that document.  We think that the best way to achieve this
 goal is to use the current GUI as a reference and to expose all information
 over the UAA that is available over the GUI.</p>

 <p>We are, of course, aware of the fact that the information available over
 the UAA will not be completely equivalent to that available over the GUI.
 Content of graphical objects for example can be exposed only rudimentary.</p>

 <p>This approach is called view based as opposed to a structure or content
 based approach that would focus not on the graphical appearance on the screen,
 but on the structure of a document's content.</p>

 <p>Consequences of employing the view based approach are for instance that in
 a Writer document a text paragraph may be split into several portions
 according to its layout on the screen.  Another example is the exposure of how
 text is broken into lines.</p>

 <p>A further reason to favor the view based approach over the content based
 one is the better consistency with the WYSIWYG paradigm.</p>
 <br>
 </li>


 <li><b>Keep it simple</b><br>

 <p>The idea behind this rule is to keep the <em>structure</em> of the UAA
 document representation as simple as possible while at the same time give
 access to as much of a document's semantical <em>content</em> as possible.
 One way to achieve that is to remove nodes from the representation tree that
 expose no content by themselves but serve only as container for other
 objects.  Such container nodes should be used only in selected places.</p>

 <p>The reason for this is a pragmatically one.  Current AT devices can't cope
 with information with a structure that is overly complex.  Moreover, no AT
 vendor will invest much time and money into supporting an API that differs too
 much from their current source of information.</p>
 <br></li>


 <li><b>Don't represent objects that lie completely off-screen</b><br>

 <p>There are two reasons for this rule.  The first one is to keep the document
 representation consistent with what is visible on the screen.  If document
 parts not visible on the screen where given access to via the UAA each AT
 device had to figure out on its own what parts are visible and shall be
 exposed to the user and which parts to hold back.</p>

 <p>The second reason is the reduction of the amount of data that has to be
 transmitted from application to AT.  This point is mainly relevant when
 application and AT are not running on the same computer.  When exposing the
 whole document over the UAA the AT would have to probe a lot of objects in
 order to determine the visible ones.</p>

 <p>There is one exception to not represent off-screen objects.  Calc tables
 will give access to all their cells at once regardless of whether they are
 on- or off-screen.  There are again two reasons for this.  The first is
 consistency with existing implementations of the AccessibleTable interface
 like the javax.swing.JTable.AccessibleJTable class.  The second reason has
 to do with cell indices.  When only the visible cells would be represented
 scrolling the document would result in each cell getting new indices--relative
 to the upper left visible cell--assigned.  This would render using indices
 virtually useless.  Representing all cells leads to indices that remain
 unchanged by scrolling.</p>

 <p>There still remains the issue of partially visible document parts.  Some,
 like text paragraphs, may be split into on- and off-screen parts.  If that
 is not possible partially visible objects are handled exactly like
 completely visible objects.</p>

 <p>Use the VISIBLE and SHOWING states to appropriately mark objects.  If
 they are completely or partially visible on the screen they are VISIBLE
 <em>and</em> SHOWING.  Objects contained in the UAA representation tree,
 that lie outside the visible area are marked as VISIBLE <em>but not</em>
 SHOWING.</p> <br></li>

 <li><b>Don't represent hidden objects</b><br>

 <p>This is very similar to the previous rule.  Objects that have been
 actively marked as hidden are not visible on the screen and therefore are
 not represented by the API.</p> <br></li>

 <li><b>Do not represent the cursor position explicitly beyond the means of
 AccessibleText</b><br>

 <p>The cursor position, i.e. the position at which text typed on the
 keyboard will be inserted into a document, has not to be explicitely exposed
 by the UAA e.g. by providing special AccessibleAction objects.  It is taken
 care of by sending events with every change of the cursor position, which
 contain information about the AccessibleText object which contains the
 cursor.  This object can then be queried for the caret position.</p>

 </li>
 </ol>
 </body>
 </html>
	<html><head>
	<meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
	</head>
	<body>
	<h2>Document representation guidelines</h2>

	<p><em>Last modification on October 31st 2001.</em></p>

	<p>The following list contains a set of guidelines for the representation of
	StarOffice/OpenOffice.org documents with the UNO Accessibility API (UAA).
	The intention of these guidelines is to define--in an application unspecific
	way--what kind of information of a document should expose over the UAA. It
	thus complements the syntactic specification made by the actual UAA
	definition.</p>

	<p>It is not the goal of these guidelines to give a detailed description of
	how to represent documents of the individual applications. That is done at
	another place.
	</p>

	<ol>
	<li><b>View based approach</b><br>
	<p>In order to let people that use different interfaces--for example the
	OpenOffice.org GUI or a Braille display--help each other with working on a
	document all of them need to have access to an <em>equivalent</em>
	representation of that document. We think that the best way to achieve this
	goal is to use the current GUI as a reference and to expose all information
	over the UAA that is available over the GUI.</p>

	<p>We are, of course, aware of the fact that the information available over
	the UAA will not be completely equivalent to that available over the GUI.
	Content of graphical objects for example can be exposed only rudimentary.</p>

	<p>This approach is called view based as opposed to a structure or content
	based approach that would focus not on the graphical appearance on the screen,
	but on the structure of a document's content.</p>

	<p>Consequences of employing the view based approach are for instance that in
	a Writer document a text paragraph may be split into several portions
	according to its layout on the screen. Another example is the exposure of how
	text is broken into lines.</p>

	<p>A further reason to favor the view based approach over the content based
	one is the better consistency with the WYSIWYG paradigm.</p>
	<br>
	</li>


	<li><b>Keep it simple</b><br>

	<p>The idea behind this rule is to keep the <em>structure</em> of the UAA
	document representation as simple as possible while at the same time give
	access to as much of a document's semantical <em>content</em> as possible.
	One way to achieve that is to remove nodes from the representation tree that
	expose no content by themselves but serve only as container for other
	objects. Such container nodes should be used only in selected places.</p>

	<p>The reason for this is a pragmatically one. Current AT devices can't cope
	with information with a structure that is overly complex. Moreover, no AT
	vendor will invest much time and money into supporting an API that differs too
	much from their current source of information.</p>
	<br></li>


	<li><b>Don't represent objects that lie completely off-screen</b><br>

	<p>There are two reasons for this rule. The first one is to keep the document
	representation consistent with what is visible on the screen. If document
	parts not visible on the screen where given access to via the UAA each AT
	device had to figure out on its own what parts are visible and shall be
	exposed to the user and which parts to hold back.</p>

	<p>The second reason is the reduction of the amount of data that has to be
	transmitted from application to AT. This point is mainly relevant when
	application and AT are not running on the same computer. When exposing the
	whole document over the UAA the AT would have to probe a lot of objects in
	order to determine the visible ones.</p>

	<p>There is one exception to not represent off-screen objects. Calc tables
	will give access to all their cells at once regardless of whether they are
	on- or off-screen. There are again two reasons for this. The first is
	consistency with existing implementations of the AccessibleTable interface
	like the javax.swing.JTable.AccessibleJTable class. The second reason has
	to do with cell indices. When only the visible cells would be represented
	scrolling the document would result in each cell getting new indices--relative
	to the upper left visible cell--assigned. This would render using indices
	virtually useless. Representing all cells leads to indices that remain
	unchanged by scrolling.</p>

	<p>There still remains the issue of partially visible document parts. Some,
	like text paragraphs, may be split into on- and off-screen parts. If that
	is not possible partially visible objects are handled exactly like
	completely visible objects.</p>

	<p>Use the VISIBLE and SHOWING states to appropriately mark objects. If
	they are completely or partially visible on the screen they are VISIBLE
	<em>and</em> SHOWING. Objects contained in the UAA representation tree,
	that lie outside the visible area are marked as VISIBLE <em>but not</em>
	SHOWING.</p> <br></li>

	<li><b>Don't represent hidden objects</b><br>

	<p>This is very similar to the previous rule. Objects that have been
	actively marked as hidden are not visible on the screen and therefore are
	not represented by the API.</p> <br></li>

	<li><b>Do not represent the cursor position explicitly beyond the means of
	AccessibleText</b><br>

	<p>The cursor position, i.e. the position at which text typed on the
	keyboard will be inserted into a document, has not to be explicitely exposed
	by the UAA e.g. by providing special AccessibleAction objects. It is taken
	care of by sending events with every change of the cursor position, which
	contain information about the AccessibleText object which contains the
	cursor. This object can then be queried for the caret position.</p>

	</li>
	</ol>
	</body>
	</html>