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

[Piñeiro <apinheiro igalia com>]

From: Joanmarie Diggs <joanied gnome org>

Awesome explanation. I were talking about this with Mario in the
office and I also didn't understand this method.

IMHO, all this information should be added in the documentation, as I
feel that the current explanation is not enough to understand what
developers require to implement. As ATK is a bunch of abstract
classes, it is not only about how to use these methods, it is also
about implement them. In the same way, I also think that for a new
developer, understanding how to use this function with the current
documentation is not enough.

We can add this as a subtitem of the item "ATK requires a improved
documentation" ;)

> 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
> 
> 
> 
> _______________________________________________
> gnome-accessibility-devel mailing list
> gnome-accessibility-devel gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-accessibility-devel