[g-a-devel] RFC: AtkText simplification (take 3)

[Mario Sanchez Prada <msanchez gnome org>]

Hi all,

Pineiro and me have been holding an interesting conversation about
this in the a11y BoF in GUADEC and we believe we have found a better
way to move forward here, which would mean not having to deprecate
individual elements of an enum nor breaking the ABI at all, while
still allowing us to cleanly provide a new set of functions that will
be handy for transitioning to the new API without after/before methods
and without _END boundaries.

The proposed solution would be as follows:

 1. Add a new enumeration independent of the old one (so we can
deprecate the whole old one) like this:

    typedef enum {
        ATK_TEXT_GRANULARITY_CHAR,
        ATK_TEXT_GRANULARITY_WORD,
        ATK_TEXT_GRANULARITY_LINE,
        ATK_TEXT_GRANULARITY_SENTENCE
    } AtkTextGranularity;

   (New name inspired in internal stuff from WebKit)

 2. Add a new function that will only need the offset and the
granularity as input parameters:

    gchar* atk_text_get_text_for_offset (AtkText *text,
                                                        gint offset,

AtkTextGranularity  granularity,
                                                        gint *start_offset,
                                                        gint *end_offset);

3. Mark the old enum (AtkTextBoundary) and the old function
atk_text_get_text_at_offset() as deprecated (the before/after versions
are already deprecated now), in favour of this new function and
enumeration.

4. Do a similar change in AT-SPI2, by adding a new
AtspiTextGranularity enum and a new atspi_text_get_text_for_offset()
function to the AtspiText interface, deprecating the old things too.

5. Add the needed bits in at-spi2-core and at-spi2-atk to implement
this new function in terms of D-Bus, effectively connecting the
servers and the clients.

6. In atspi2-atk bridge, check which version of ATK a specific
application is implementing (using atk_get_version()) when
implementing this new atk_text_get_text_for_offset(), so we know
whether we can call atk_text_get_text_for_offset() or we need to use
the old atk_text_get_text_at_offset() and a *_START boundary instead
(for implementors of older versions of ATK).

7. Update documentation :)

We believe that this is the best approach in the way that it allows a
clean transition and a less confusing API.

Feedback is welcome!

Thanks,
Mario