Re: [g-a-devel] Doubt about AtkHypertext interface

[Joanmarie Diggs <joanied gnome org>]

Hey Mario.

> I'm currently trying to add support for AtkHypertext, AtkHyperlink and
> AtkHyperlinkImpl in WebKitGTK 

Yay! And thank you. :-)

> and I found the following function
> confusing:
> 
>   gint atk_hypertext_get_link_index (AtkHypertext *hypertext, 
>                                      gint char_index);
> 
> According to the documentation: 
> 
> "Gets the index into the array of hyperlinks that is associated with the
> character specified by char_index."
> 
> ..but still, I can't get what the char_index is and what it's used for.

Consider this paragraph:

    <p>This <a href='foo'>is</a> a <a href='bar'>test</a>.</p>

char_index refers to the offset within the string, thus:

T h i s   i s   a   t e s t .
0 1 2 3 4 5 6 7 8 9 A B C D E

The question atk_hypertext_get_link_index is answering is: Is the
character at index/offset i part of a link -- and if so which link?

Thus:

* For indices 5 and 6, I'd expect atk_hypertext_get_link_index to 
  return 0 because 'is' is text associated with the first link.

* For indices 10 through 13, I'd expect 1 to be returned because 'test' 
  is text associated with the second link.

* For all other indices, I'd expect -1 to be returned because the    
  characters at those indices are not associated with any link.

As for why we might want to use it:

Let's say the user is arrowing within the text by character or by word.
WebKitGtk emits an object:text-caret-moved event. Orca needs to present
that new character or word in response -- and we'd like to let the user
know if that new character/word is part of a link.

In this example, what we know from the event is the AtkObject associated
with the event (here it would be the paragraph), and we know the offset
to which the caret was moved (event.detail1). From these two items we
can find out if we need to say 'link' or not based on the return value
of atk_hypertext_get_link_index().

Taking it a step further, since I'm already deep diving :-), let's say
the return value is 0, so Orca announces 'link.' The user might then
want to know the URI associated with the link at the location of the
caret and do a whereAmI. The return value tells us which link it is. We
can get that link via atk_hypertext_get_link() and, having done so, use
atk_hyperlink_get_uri() to report 'foo'.

Thanks again for all your work! Sorry for being long-winded. And I look
forward to meeting you very, very soon. :-)

--joanie