From: Joanmarie Diggs <[email protected]> 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 > [email protected] > http://mail.gnome.org/mailman/listinfo/gnome-accessibility-devel _______________________________________________ gnome-accessibility-devel mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-accessibility-devel
