[g-a-devel]comments on implementing hypertext in mozilla

[Gilbert Fang <gf g-a-devel sun com>]

Hi, Kyle and Jay
 Aaronl want me to write comments in the codes. But this comments is too
large for the source file. I will add the main contents in source code file.
Now, I strongly need your signature  and suggestions on
the comments to convince Aaronl to accept  my way to implementing . 
If  conveniently, please fwo this email to Aaronl with your  suggestions.

Best regards 
Gilbert

Title: hometest

Implementing  hypertext and hyperlink interface in  mozilla
Gilbert(Gilbert Fang sun com)
June 25, 2002 

Q:What is hypertext?
A:hypertext is a piece of text with links. 

Q:what is use of hypertext?
A:By hypertext interface, ATs can get information about 
1) how many hyperlinks in this hypertext.(readonly attribute long links;)
2) get the hyperlink object by index.   (nsIAccessibleHyperLink getLink (in long index);)
3) get the index by hypertext character index. (long getLinkIndex (in long charIndex);)


Q:What is link/anchor?
A:link/anchor is a hyper reference in html. There are two kind of hyperlink: single-anchor and multi-anchor.
For example,   <a href=""> first link  </a> is can be one hyperlink with one ahchor.
And   for the following html piece,
<map name=m>
<area coords="0,0,60,52" href=""><area coords="61,0,130,52" href=""><area coords="131,0,210,52" href=""><area coords="450,0,530,52" href=""><area coords="531,0,605,52" href=""><area coords="606,0,668,52" href=""></map>
<img width=668 height=53 border=0  src="" alt=Yahoo>
it can be one hyperlink with six ahchors.     

Q:What is hyperlink?
A:Hyperlink here is a little different from other places. hyperlink is anchor or ONE SET OF ANCHORS in hypertext.
IMPORTANT: a hyperlink object  MUST BE IN one hypertext. 

Q:What is use of hyperlink?
A: By hyperlink interface, ATs can get inforamtion about 
1)how many anchors/ how any urls you can go  in this hyperlink ;(readonly attribute long anchors;)
2)the index of first character of the hyperlink in the hypertext which the hyperlink  is in; (readonly attribute long startIndex;)
3)the index of last character of the hyperlink in the hypertext which the hyperlink is in; (readonly attribute long endIndex;)
4)nsIURI for each anchors; (nsIURI getURI (in long i);)
5)the accNode for each anchors;( nsIAccessible getObject (in long i);)
6)whether this hyperlink is valid in its hypertext, (boolean isValid ();)  I have not found any situation to make the hyperlink inValid.


Q:Why are there more than one hyperlink for the same html element<a href="">A:That is because this element can be in different hypertext. 
For example, in the following sample ---- "Sample Nozilla Page",
1) the whole contents as ONE hypertext(hypertext_all).
2) at the same time, that html table cell (1,1) can be another hypertext(hypertext_one).
of course, there may be other hypertext objects, but I need not to point out them all.
For the html element DOM_node_a (<a  href="file:///E:/temp/"> The Nozilla Organization</a>)
If you get a hyperlink(hyperlink_a) from the hypertext_all, then this hyperlink_a is the one  in hypertext_all, that is 
hyperlink_a.startIndex should be 17--the 'T' in "Nozilla Home PageThe Nozilla Organization......."
but If you get hyperlink(hyperlink_b) for the same DOM node(DOM_node_a), but from the hypertext_a, then this hyperlink_b 
is the one in hypertext_b,that is hyperlink_b.startIndex should be 0-- the 'T' in "The Nozilla OrganizationFeedback".
That is why hyperlink have to have a reference to the hypertext(in my code, aAssociatecDOMNode) which it is in.


Q:How to access mozilla by hypertext?
A:Actually, this is the most important part for implementing these two interfaces. 
I have designed  three level to implement it.
1)Theoretically Way, every piece of html element can be accessed as hypertext. 
( I have made the nsAccessible to support the nsIAccessibleHyperText. It has works well in our internal source tree.)
In this case, for the sample "Sample Nozilla Page", the access objects  view will be like

hypertext_all---accNode(ROLE_PANE)
hypertext_A--accNode(ROLE_TEXT)

hypettext_one--accNode(ROLE_CELL)	hypettext_B--accNode(ROLE_CELL)
	hypettext_C--accNode(ROLE_CELL)

I only show main object here.

2)Flexible Way, only some kind of html element can be accessed as hypertext. At least, the whole content pane, the html table cell,html table caption, 
html anchor element (<a href></a>), client-side image map are hypertext. 
In this case, the "Sample Nozilla Page" will show access objects  like

hypertext_all---accNode(ROLE_PANE)

hypettext_one--accNode(ROLE_CELL)	hypettext_B--accNode(ROLE_CELL)
	hypettext_C--accNode(ROLE_CELL)

Comparing to Theoretically Way, the hypertext_A--accNode(ROLE_TEXT) disappeared. 

3) Simplest Way, only implementing   hypertext for html anchor element (<a href></a>) and  client-side image map. And each hypertext can only have 
one hyperlink. The hypertext and hyperlink have to be for the same DOM node. 
In this case, access objects will  like

accNode(ROLE_PANE)

hypettext_1--accNode(ROLE_LINK) hypettext_2--accNode(ROLE_LINK)	accNode(ROLE_TEXT)
	accNode(ROLE_TEXT) accNode(ROLE_TEXT) hypettext_3--accNode(ROLE_LINK) accNode(ROLE_TEXT)  hypettext_3--accNode(ROLE_LINK) accNode(ROLE_TEXT)

Now, I have implemented in "Theoretically Way". But Kyle prfer the "Flexible Way" with only for "the whole content pane" recently.
I will paste the my patch  in "Theoretically Way" FYI.

---

Nozilla Home Page

The Nozilla Organization Feedback	Nozilla News
	Nozilla 1.0 Released We are pleased to announce the release of Nozilla 1.0, available for download now. Thanks to everyone who made this possible.

---

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>Sample Nozilla Page</title>
                           
  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
</head>
<body>
    <br>
    Nozilla Home Page<br>
    <br>
       
<table cellpadding="2" cellspacing="2" border="1" width="100%">
      <tbody>
        <tr>
          <td valign="top" rowspan="2" colspan="1">  <a  href="file:///E:/temp/"> The Nozilla Organization</a><br>
                             <a href="file:///E:/temp/feedback.html">  Feedback       </a><br>
          </td>
          <td valign="top">Nozilla News<br>
          </td>
          </tr>
          <tr>
          <td valign="top">
          <p><b>Nozilla 1.0 Released</b><br>
We are pleased to announce the release of Nozilla 1.0, available for  <a
 href="file:///E:/temp/releases/stable.html">download</a> now. Thanks to
          <a href="file:///E:/temp/credits/">everyone</a> who made this possible. 
          </p>
          </td>
       </tr>
               
</tbody>    
</table>
       
</body>
</html>

---