As far as I remember myself I've always been in touch with ATK text interface implementation in Mozilla. I started from writing and reviewing some patches in far 2006 year. But I didn't really understand that piece of code so I wasn't sure that a change here don't break things there. At some point we decided that we should get an automated test coverage for the text interface before we do any serious work in this area. At least that allowed us to be sure to a certain extent we don't regress badly from a single bug fix. And then I helped my colleagues in test suite creation. As part of this work we caught a bug in ATK spec (thanks to Evan Yan, a Mozilla community member and those times Sun engineer). So that wasn't easy. It wouldn't be a lie if I said that I've never seen a more complicated API for the things it's designed for.
I should notice that roughly speaking IAccessible2 text interface implementation in Firefox is done via ATK text interface. So having a bad implementation in ATK we deliver all bugs right to IAccessible2 screen readers. It's a hot problem in other words. Recently I've felt myself brave enough (again) to say: we should stop this shame. And I started to look at the code and the spec trying to untwist things. And then I realized I still don't have a good perception of ATK text. First of all I thought it'd be good to add some drawings to stingy ATK spec to let me and everybody else check easily whether the expected results are correct actually.
ATK provides bunch of methods to get a text:
Of course ATK provides a bunch of other methods but they are trivial and it doesn't make sense to even mention them. Each of methods above take AtkTextBoundary as an argument and its values are:
If you didn't planned to read the ATK spec or dig into details then you can skip this chapter and move to the pictures part. Otherwise this chapter might be useful since it has some clarifications.
First of all, here are some terms which are used in the spec but aren't defined there:
Also we need to mention edge cases: imaginary offsets. Say we have a paragraph:
<p>hello</p>
and then we do
gint startOffset = 0, endOffset = 0;
atk_text_get_text_at_offset(accessible, 1,
ATK_TEXT_BOUNDARY_WORD_START,
&startOffset, &endOffset);
atk_text_get_text_at_offset(accessible, 1,
ATK_TEXT_BOUNDARY_WORD_END,
&startOffset, &endOffset);
In both cases we expect "hello" string with (0, 5) start and end offsets otherwise there's no way traverse this paragraph by words. But actually it goes with spec: "The returned string will contain the word at the offset if the offset is inside a word". But this means that 0 and 5 offsets are both start and end offset the same time because "the returned string is from the word start at or before the offset to the word start after the offset" and "the returned string is from the word end before the offset to the word end at or after the offset".
Summarizing it all a zero offset (0) and a last offset (character count) are special offsets and can be treated as word start, word end, line start and line end offsets.
Update. The proposed algorithm must be corrected to handle edge offsets properly, see ATK text pitfalls. I won't spend time to update it since Joanie proposed ATK text simplification and hopefully it will be accepted in foreseeable future.
So we are ready to put the spec verbosity into nice pictures.
WORD_START and LINE_START boundaries are illustrated this way (X symbol designates the initial offset):
WORD_END and LINE_END boundaries:
Move backward to the boundary and then (if was successful) move forward. The start offset is before the initial offset, the end offset is at or after the initial offset.
I should notice that roughly speaking IAccessible2 text interface implementation in Firefox is done via ATK text interface. So having a bad implementation in ATK we deliver all bugs right to IAccessible2 screen readers. It's a hot problem in other words. Recently I've felt myself brave enough (again) to say: we should stop this shame. And I started to look at the code and the spec trying to untwist things. And then I realized I still don't have a good perception of ATK text. First of all I thought it'd be good to add some drawings to stingy ATK spec to let me and everybody else check easily whether the expected results are correct actually.
Preliminaries
ATK provides bunch of methods to get a text:
Of course ATK provides a bunch of other methods but they are trivial and it doesn't make sense to even mention them. Each of methods above take AtkTextBoundary as an argument and its values are:
- char (trivial)
- word start and word end
- line start and line end
- sentence start and sentence end (not implemented in Firefox)
About terms: a chapter for the advanced
If you didn't planned to read the ATK spec or dig into details then you can skip this chapter and move to the pictures part. Otherwise this chapter might be useful since it has some clarifications.
First of all, here are some terms which are used in the spec but aren't defined there:
- word start offset - an offset where the word starts, for example, "hello, all" has two word start offsets: 0 for "hello" and 7 for "all";
- word end offset - 5 for "hello", i.e. an offset after 'o' character, and 10 for "all";
- inside word offset - any offset between word start and end offset (including boundaries), in our case these are 0-5 and 7-9 offsets;
- outside word offset - everything that is not inside a word, in our case this is only 6 offset.
Also we need to mention edge cases: imaginary offsets. Say we have a paragraph:
<p>hello</p>
and then we do
gint startOffset = 0, endOffset = 0;
atk_text_get_text_at_offset(accessible, 1,
ATK_TEXT_BOUNDARY_WORD_START,
&startOffset, &endOffset);
atk_text_get_text_at_offset(accessible, 1,
ATK_TEXT_BOUNDARY_WORD_END,
&startOffset, &endOffset);
In both cases we expect "hello" string with (0, 5) start and end offsets otherwise there's no way traverse this paragraph by words. But actually it goes with spec: "The returned string will contain the word at the offset if the offset is inside a word". But this means that 0 and 5 offsets are both start and end offset the same time because "the returned string is from the word start at or before the offset to the word start after the offset" and "the returned string is from the word end before the offset to the word end at or after the offset".
Summarizing it all a zero offset (0) and a last offset (character count) are special offsets and can be treated as word start, word end, line start and line end offsets.
A Quick-n-Easy Guide
Update. The proposed algorithm must be corrected to handle edge offsets properly, see ATK text pitfalls. I won't spend time to update it since Joanie proposed ATK text simplification and hopefully it will be accepted in foreseeable future.
So we are ready to put the spec verbosity into nice pictures.
atk_text_get_text_at_offset
WORD_START and LINE_START boundaries are illustrated this way (X symbol designates the initial offset):
or
Move forward to the boundary and then (if was successful) move backward. The start offset is at or before the initial offset, the end offset is after the initial offset.
WORD_END and LINE_END boundaries:
or
Move backward to the boundary and then (if was successful) move forward. The start offset is before the initial offset, the end offset is at or after the initial offset.
atk_text_get_text_before_offset
WORD_START and LINE_START boundaries:
or
If the initial offset is the boundary then move backward to find the start offset. Otherwise move backward twice to pick up the start and end offsets.
WORD_END and LINE_END boundaries:
atk_text_get_after_offset
WORD_START and LINE_START boundaries:
WORD_END and LINE_END boundaries:
or
If the initial offset is the boundary then move forward to find the end offset. Otherwise move forward twice to pick up the start and end offsets.
That's all. Hallelujah to Love!
P.S. Well if I'm wrong in sayings above then you'd better say it otherwise this will be implemented in Firefox soon ;)
No comments:
Post a Comment